PHP マニュアル: 結果セットから、残っている行を取得する

説明

public array PDOStatement::fetchAll(int $mode = PDO::FETCH_DEFAULT)

public array PDOStatement::fetchAll(int $mode = PDO::FETCH_COLUMN, int $column)

public array PDOStatement::fetchAll(int $mode = PDO::FETCH_CLASS, string $class, arraynull $constructorArgs)

public array PDOStatement::fetchAll(int $mode = PDO::FETCH_FUNC, callable $callback)

パラメータ

mode

PDOStatement::fetch で説明されている、返される配列の内容を制御します。デフォルトは PDO::ATTR_DEFAULT_FETCH_MODE の値 (デフォルトは PDO::FETCH_BOTH) です。

結果セットから単一カラムの全ての値を含む配列を返す場合、 PDO::FETCH_COLUMN を指定します。 column パラメータにどのカラムを返すかを指定することができます。

配列のキーに(連続した数値ではなく)あるカラムの値を割り当てたい場合 SQL のカラムリスト中のカラム名を指定すると同時に PDO::FETCH_UNIQUE を指定します。このカラムはユニークである必要があります。そうしないと、データが失われます。

指定したカラムの値によってグループ化した3次元配列を返す場合、 SQL のカラムリスト中のカラム名を指定すると同時に PDO::FETCH_GROUP を指定します。

結果をグループ化した2次元配列で返す場合、 PDO::FETCH_COLUMN と一緒に PDO::FETCH_GROUP bit-OR で指定します。この結果は、最初のカラムでグループ化され、配列の要素の値はふたつめのカラムの対応するエントリの配列になります。

以下は mode の値によって決まる動的なパラメータです。これらは、名前付き引数と一緒に使うことは出来ません。

column: PDO::FETCH_COLUMN と一緒に使います。0 から始まる番号のカラムを返します。
class: PDO::FETCH_CLASS と一緒に使います。ここで指定したクラスのインスタンスを返します。各行のカラムがクラスのプロパティ名にマッピングされます。
constructorArg: mode が PDO::FETCH_CLASS のときに使う、独自のクラスコンストラクタへの引数。
callback: PDO::FETCH_FUNC と一緒に使います。ここで指定した関数をコールした結果を返します。各行のカラムを関数コール時のパラメータとします。

戻り値

PDOStatement::fetchAll は、結果セットに残っている全ての行を含む配列を返します。この配列は、カラム値の配列もしくは各カラム名に対応するプロパティを持つオブジェクトとして各行を表します。取得結果がゼロ件だった場合は空の配列を返します。

大きな結果セットをフェッチするためにこのメソッドを使用することは、システムとネットワークリソースに大量の要求を行うことになります。 PHP で全てのデータ処理と操作を行うよりも、データベースサーバー側で結果セットを操作することを検討してください。例えば、PHP で処理を行う前に SQL で WHERE 句や ORDER BY 句を使用し、結果を制限することです。

エラー / 例外

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

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

変更履歴

バージョン	説明
8.0.0	このメソッドは、常に配列を返すようになりました。これより前のバージョンでは、失敗した場合に `false` を返す可能性がありました。

例

例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
PDOStatement::fetch
PDOStatement::fetchColumn
PDO::prepare
PDOStatement::setFetchMode