(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)
PDOStatement::fetch — 結果セットから次の行を取得する
$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_NAMED:
PDO::FETCH_ASSOC と同じ形式の配列を返します。
ただし、同じ名前のカラムが複数あった場合は、そのキーが指す値は、
同じ名前のカラムのすべての値を含む配列になります。
PDO::FETCH_NUM:
結果セットの 0
から始まるカラム番号を添字とする配列を返します。
PDO::FETCH_BOTH:
結果セットのカラム名と
0 から始まるカラム番号を添字とする配列を返します。
PDO::FETCH_NUM と
PDO::FETCH_ASSOC を組み合わせたものと実質的に同等です。
PDO::FETCH_BOUND:
true を返し、結果セットのカラムの値を
PDOStatement::bindColumn()
メソッドでバインドされた PHP 変数に代入します。
PDO::FETCH_OBJ:
結果セットのカラム名と同名のプロパティを持つ
stdClass のインスタンスを返します。
PDO::FETCH_CLASS:
要求されたクラスの新規インスタンスを返します。
PDOStatement::setFetchMode()
でクラスを設定していない場合、このモードは
PDO::FETCH_CLASSTYPE と組み合わせる必要があります。
組み合わせた場合は、インスタンス化するクラスの名前として最初のカラムの値を使います。
デフォルトでは、結果セットのカラムをクラスのプロパティにマップして
オブジェクトを初期化します。
この処理はコンストラクタをコールする前に行われるので、
プロパティのアクセス権に関係なく、たとえ
readonly
としてマークされていてもプロパティに値を設定できます。
ただし、コンストラクタ自身がプロパティを初期化しない場合に限ります。
クラスにプロパティが存在しない場合は、マジックメソッド
__set()
が存在すればコールされます。
マジックメソッドが存在しない場合、public プロパティが動的に作成されます。
PDO::FETCH_PROPS_LATE フラグを使うとこの動作を変更でき、
プロパティに値を設定する前にコンストラクタがコールされるようになります。
PDO::FETCH_PROPS_LATE を使うかどうかに関係なく、
カラムの値はコンストラクタの引数として渡されません。
渡されるのは、PDOStatement::setFetchMode()
で指定した引数だけです。
PDO::FETCH_INTO:
結果セットのカラムを、クラス内の対応する名前のプロパティにマップして、
要求されたクラスの既存のインスタンスを更新します。
PDO::FETCH_LAZY:
PDO::FETCH_BOTH と PDO::FETCH_OBJ の
動作を組み合わせたもので、PDORow オブジェクトを返します。
カラムの値は、プロパティにアクセスした時点で取得されます。
cursorOrientation
スクロール可能なカーソルを表す PDOStatement オブジェクトの場合、
この値により呼び出し側に返される行を定義します。
この値は、PDO::FETCH_ORI_* 定数のどれかと
する必要があり、
PDO::FETCH_ORI_NEXT がデフォルトとなっています。
PDOStatement に対してスクロール可能なカーソルを要求するためには、
PDO::prepare() を用いて SQL ステートメントを
準備する際、
PDO::ATTR_CURSOR 属性に
PDO::CURSOR_SCROLL を設定する必要があります。
cursorOffset
cursorOrientation 引数の値が
PDO::FETCH_ORI_ABS の場合、この値は、
取得する行の結果セット内での絶対位置を指定します。
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
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE fruit (name VARCHAR(100), colour VARCHAR(100))");
$db->exec("INSERT INTO fruit (name, colour) VALUES
('apple', 'red'),
('banana', 'yellow'),
('orange', 'orange'),
('kiwi', 'green')");
$sth = $db->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Exercise PDOStatement::fetch styles */
echo "PDO::FETCH_ASSOC: ";
echo "Return next row as an array indexed by column name\n";
$result = $sth->fetch(PDO::FETCH_ASSOC);
var_dump($result);
echo "\n";
echo "PDO::FETCH_BOTH: ";
echo "Return next row as an array indexed by both column name and number\n";
$result = $sth->fetch(PDO::FETCH_BOTH);
var_dump($result);
echo "\n";
echo "PDO::FETCH_LAZY: ";
echo "Return next row as a PDORow object with column names as properties\n";
$result = $sth->fetch(PDO::FETCH_LAZY);
var_dump($result);
echo "\n";
echo "PDO::FETCH_OBJ: ";
echo "Return next row as an stdClass object with column names as properties\n";
$result = $sth->fetch(PDO::FETCH_OBJ);
var_dump($result);
echo "\n";
?>上の例の出力は以下となります。
PDO::FETCH_ASSOC: Return next row as an array indexed by column name
array(2) {
["name"]=>
string(5) "apple"
["colour"]=>
string(3) "red"
}
PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
array(4) {
["name"]=>
string(6) "banana"
[0]=>
string(6) "banana"
["colour"]=>
string(6) "yellow"
[1]=>
string(6) "yellow"
}
PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
object(PDORow)#3 (3) {
["queryString"]=>
string(30) "SELECT name, colour FROM fruit"
["name"]=>
string(6) "orange"
["colour"]=>
string(6) "orange"
}
PDO::FETCH_OBJ: Return next row as an stdClass object with column names as properties
object(stdClass)#4 (2) {
["name"]=>
string(4) "kiwi"
["colour"]=>
string(5) "green"
}
例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.