コレクションに問い合わせ、単一の要素を返す

# 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 をスローします。

### 変更履歴

バージョン | 説明
--- | ---
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