結果セットから次の行を取得する

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — 結果セットから次の行を取得する

### 説明

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

PDOStatementオブジェクトに関連付けられた結果セットから1行取得します。 `mode` パラメータは、PDO がその行をどの様に返すかを決定します。

### パラメータ

`mode`

  次のレコードを呼び出し元に返す方法を制御します。 この値は、`PDO::FETCH_*` 定数のどれかで、 デフォルトは `PDO::ATTR_DEFAULT_FETCH_MODE` の値 (そのデフォルトは `PDO::FETCH_BOTH`) です。

  - `PDO::FETCH_ASSOC`: は、結果セットに 返された際のカラム名で添字を付けた配列を返します。

  - `PDO::FETCH_BOTH` (デフォルト): 結果セットに返された際のカラム名と 0 で始まるカラム番号で添字を付けた配列を返します。

  - `PDO::FETCH_BOUND`: `true` を返し、結果セットのカラムの値を PDOStatement::bindColumn() メソッドでバインドされた PHP 変数に代入します。

  - `PDO::FETCH_CLASS`: 要求されたクラスの新規インスタンスを返します。 結果セットのカラムをクラスのプロパティにマップしつつ、 オブジェクトは初期化されます。 この処理はコンストラクタをコールする前に行われるので、 プロパティのアクセス権に関係なく、たとえ `readonly` としてマークされていてもプロパティの値を集めることができます。 クラスにプロパティが存在しない場合は、マジックメソッド __set() が存在すればコールされます。 マジックメソッドが存在しない場合、public プロパティが動的に作成されます。 しかしながら、`PDO::FETCH_PROPS_LATE` が指定されている場合は、プロパティの値を集める 前 にコンストラクタがコールされます。 `mode` に PDO::FETCH_CLASSTYPE が 含まれている場合 (例: `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE`) は、最初のカラムの値から クラス名を決定します。

  - `PDO::FETCH_INTO`: 結果セットのカラムがクラス内の名前付けされたプロパティに マッピングされている要求された既存インスタンスを更新します。

  - `PDO::FETCH_LAZY`: `PDO::FETCH_BOTH` と`PDO::FETCH_OBJ`の 組合せで、アクセスされるオブジェクトプロパティ名を作成する PDORow オブジェクトを返します。

  - `PDO::FETCH_NAMED`: `PDO::FETCH_ASSOC` と同じ形式の配列を返します。 ただし、同じ名前のカラムが複数あった場合は、そのキーが指す値は、 同じ名前のカラムのすべての値を含む配列になります。

  - `PDO::FETCH_NUM`: 結果セットに返された際の 0 から始まるカラム番号を添字とする配列を返します。

  - `PDO::FETCH_OBJ`: 結果セットに返された際のカラム名と同名のプロパティを有する 匿名のオブジェクトを返します。

  - `PDO::FETCH_PROPS_LATE`: `PDO::FETCH_CLASS` とともに使用すると、 まずクラスのコンストラクタを呼び出してから、カラムの値をプロパティに代入します。

`cursorOrientation`

  スクロール可能なカーソルを表す PDOStatement オブジェクトの場合、 この値により呼び出し側に返される行を定義します。 この値は、`PDO::FETCH_ORI_*` 定数のどれかと する必要があり、 `PDO::FETCH_ORI_NEXT` がデフォルトとなっています。 PDOStatement に対してスクロール可能なカーソルを要求するためには、 PDO::prepare() を用いて SQL ステートメントを 準備する際、 `PDO::CURSOR_SCROLL` に `PDO::ATTR_CURSOR` 属性を設定する必要があります。

`cursorOffset`

  スクロール可能なカーソルを表すPDOStatementオブジェクトの場合で、 `cursorOrientation` パラメータが `PDO::FETCH_ORI_ABS`に設定された場合、この値により 取得される結果セットの行の絶対位置が指定されます。

  スクロール可能なカーソルを表すPDOStatementオブジェクトの場合で、 `cursorOrientation` パラメータが `PDO::FETCH_ORI_REL`に設定された場合、この値は、 PDOStatement::fetch() がコールされる前のカーソルの 位置を基準として取得する行の位置を指定します。

### 戻り値

この関数が成功した場合の戻り値は、取得形式によって異なります。 失敗した場合、または行が残っていない場合は、常に `false` を返します。

### エラー / 例外

`PDO::ATTR_ERRMODE` が `PDO::ERRMODE_WARNING` に設定されていた場合、`E_WARNING` レベルのエラーが発生します。

`PDO::ATTR_ERRMODE` が `PDO::ERRMODE_EXCEPTION` に設定されていた場合、PDOException がスローされます。

### 例

例1 異なる取得方法で行を取得する

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Exercise PDOStatement::fetch styles */
    print "PDO::FETCH_ASSOC: ";
    print "Return next row as an array indexed by column name\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Return next row as an array indexed by both column name and number\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Return next row as a PDORow object with column names as properties\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print $result->name;
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Return next row as an anonymous object with column names as properties\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->NAME;
    print "\n";
    ?>

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

    PDO::FETCH_ASSOC: Return next row as an array indexed by column name
    Array
    (
        [name] => apple
        [colour] => red
    )

    PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
    Array
    (
        [name] => banana
        [0] => banana
        [colour] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
    PDORow Object
    (
        [name] => orange
        [colour] => orange
    )

    PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
    kiwi

例2 スクロール可能なカーソルで行を取得する

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Reading forwards:\n";
    readDataForwards($conn);

    print "Reading backwards:\n";
    readDataBackwards($conn);
    ?>

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

    Reading forwards:
    21    10    5
    16    0     5
    19    20    10

    Reading backwards:
    19    20    10
    16    0     5
    21    10    5

例3 構築の順序

`PDO::FETCH_CLASS` でオブジェクトを取得するときには、 まずオブジェクトのプロパティへの代入を終えてから、そのクラスのコンストラクタを実行します。 `PDO::FETCH_PROPS_LATE` を指定した場合はこの順序が逆転します。 つまり、まずコンストラクタを呼び出してから、プロパティへの代入を行います。

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "I am {$this->name}.\n";
            } else {
                echo "I don't have a name yet.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");
    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();
    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();
    ?>

上の例の出力は、 たとえば以下のようになります。

    I am Alice.
    I am Alice.
    I don't have a name yet.
    I am Bob.

### 参考

- PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
- PDOStatement::execute() - プリペアドステートメントを実行する
- PDOStatement::fetchAll() - 結果セットから、残っている行を取得する
- PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す
- PDOStatement::fetchObject() - 次の行を取得し、それをオブジェクトとして返す
- PDOStatement::setFetchMode() - この文に対するデフォルトのフェッチモードを設定する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open