PDOStatement::fetch

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

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

説明

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

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

パラメータ

mode

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

PDO::FETCH_ASSOC: は、結果セットに返された際のカラム名で添字を付けた配列を返します。
PDO::FETCH_BOTH (デフォルト): 結果セットに返された際のカラム名と 0 で始まるカラム番号で添字を付けた配列を返します。
PDO::FETCH_BOUND: true を返し、結果セットのカラムの値を PDOStatement::bindColumn() メソッドでバインドされた PHP 変数に代入します。
PDO::FETCH_CLASS: 要求されたクラスの新規インスタンスを返します。結果セットのカラムをクラスのプロパティにマップしつつ、オブジェクトは初期化されます。この処理はコンストラクタをコールする前に行われるので、プロパティのアクセス権に関係なく、たとえ 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() - この文に対するデフォルトのフェッチモードを設定する