PDO::setAttribute

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

PDO::setAttribute — 属性を設定する

説明

public PDO::setAttribute(int $attribute, mixed $value): bool

データベースハンドルの属性を設定します。利用可能な通常の属性は以下の通りです。いくつかのドライバでは、ドライバ固有の属性を使用することが可能です。ドライバ固有の属性は、他のドライバでは使っては いけない ことに注意して下さい。

PDO::ATTR_CASE

強制的にカラム名を指定したケースにします。以下の値のうち、ひとつを指定できます:

PDO::CASE_LOWER: 強制的にカラム名を小文字にする。
PDO::CASE_NATURAL: データベースドライバによって返されるカラム名をそのままにする。
PDO::CASE_UPPER: 強制的にカラム名を大文字にする。

PDO::ATTR_ERRMODE

PDO のエラーレポートモード。以下の値のうち、ひとつを指定できます:

PDO::ERRMODE_SILENT: エラーコードのみを設定する。
PDO::ERRMODE_WARNING: E_WARNING を発生させる。
PDO::ERRMODE_EXCEPTION: PDOException をスローします。

PDO::ATTR_ORACLE_NULLS

注意: この属性は Oracle だけでなく、全てのドライバで利用可能です。

null と空文字列を変換するかどうか、および、どのように変換するかを指定します。以下の値のうち、ひとつを指定できます:

PDO::NULL_NATURAL: 変換を行わない。
PDO::NULL_EMPTY_STRING: 空文字列を null に変換する。
PDO::NULL_TO_STRING: null を空文字列に変換する。

PDO::ATTR_STRINGIFY_FETCHES

フェッチする際、数値を文字列に変換するかどうかを指定します。 bool の値を指定します: 変換を有効にする場合 true、無効にする場合、false にします。

PDO::ATTR_STATEMENT_CLASS

PDOStatement から派生した、ユーザーが提供するステートメントクラスを設定する。 array(string classname, array(mixed constructor_args)) の形式でなければいけません。

警告

永続的な PDO インスタンスは使用できません。

PDO::ATTR_TIMEOUT

タイムアウト秒数を指定します。数値を指定します。

注意:
すべてのドライバがこのオプションに対応しているわけではありません。また、ドライバによっては意味が異なることがあります。たとえば SQLite は書き込み可能なロックを確保するのをこの秒数まで待ち続けますが、他のドライバでは、この秒数を接続時のタイムアウトや読み込みのタイムアウトとして扱うことがあります。

PDO::ATTR_AUTOCOMMIT

注意: OCI, Firebird, MySQL でのみ利用可能です。

それぞれの単一文で自動コミットするかどうか。 bool の値を指定します: 自動コミットを有効にする場合 true、無効にする場合、false にします。デフォルトは true です。

PDO::ATTR_EMULATE_PREPARES

注意: OCI, Firebird, MySQL でのみ利用可能です。

プリペアドステートメントのエミュレーションを有効または無効にします。ドライバによっては、ネイティブのプリペアドステートメントをサポートしていなかったり完全には対応していなかったりするものがあります。 true を指定すると、プリペアドステートメントを常にエミュレートします。そうでない場合、ネイティブのプリペアドステートメントを使おうとします。ドライバが現在のクエリを正しく準備できなかった場合は、常にエミュレート方式を使います。

PDO::MYSQL_ATTR_USE_BUFFERED_QUERY

注意: MySQL でのみ利用可能です。

バッファされたクエリを使うかどうかを指定します。 bool の値を指定します: バッファされたクエリを有効にする場合 true、無効にする場合、false にします。デフォルトは true です。

PDO::ATTR_DEFAULT_FETCH_MODE

デフォルトのフェッチモードを設定します。このモードと使い方についての説明は、 PDOStatement::fetch() のドキュメントを参照ください。

パラメータ

attribute: 変更する属性。
value: attribute に設定する値。属性によっては、特定の型が必要かもしれません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

PDO::getAttribute() - データベース接続の属性を取得する
PDOStatement::getAttribute() - 文の属性を取得する
PDOStatement::setAttribute() - 文の属性を設定する

Improve This Page

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 8 notes

down

124

colinganderson [at] gmail [dot] com ¶

17 years ago

Because no examples are provided, and to alleviate any confusion as a result, the setAttribute() method is invoked like so:

setAttribute(ATTRIBUTE, OPTION);

So, if I wanted to ensure that the column names returned from a query were returned in the case the database driver returned them (rather than having them returned in all upper case [as is the default on some of the PDO extensions]), I would do the following:

<?php
// Create a new database connection.
$dbConnection = new PDO($dsn, $user, $pass);

// Set the case in which to return column_names.
$dbConnection->setAttribute(PDO::ATTR_CASE, PDO::CASE_NATURAL);
?>

Hope this helps some of you who learn by example (as is the case with me).

.Colin

down

yeboahnanaosei at gmail dot com ¶

6 years ago

This is an update to a note I wrote earlier concerning how to set multiple attributes when you create you PDO connection string.

You can put all the attributes you want in an associative array and pass that array as the fourth parameter in your connection string. So it goes like this: 
<?php
$options = [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_CASE => PDO::CASE_NATURAL,
    PDO::ATTR_ORACLE_NULLS => PDO::NULL_EMPTY_STRING
];

// Now you create your connection string
try {
    // Then pass the options as the last parameter in the connection string
    $connection = new PDO("mysql:host=$host; dbname=$dbname", $user, $password, $options);

    // That's how you can set multiple attributes
} catch(PDOException $e) {
    die("Database connection failed: " . $e->getMessage());
}
?>

down

gregory dot szorc at gmail dot com ¶

17 years ago

It is worth noting that not all attributes may be settable via setAttribute().  For example, PDO::MYSQL_ATTR_MAX_BUFFER_SIZE is only settable in PDO::__construct().  You must pass PDO::MYSQL_ATTR_MAX_BUFFER_SIZE as part of the optional 4th parameter to the constructor.  This is detailed in http://bugs.php.net/bug.php?id=38015

down

yeboahnanaosei at gmail dot com ¶

7 years ago

Well, I have not seen it mentioned anywhere and thought its worth mentioning. It might help someone. If you are wondering whether you can set multiple attributes then the answer is yes.

You can do it like this:
try {
    $connection = new PDO("mysql:host=$host; dbname=$dbname", $user, $password);
    // You can begin setting all the attributes you want.
    $connection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $connection->setAttribute(PDO::ATTR_CASE, PDO::CASE_NATURAL);
    $connection->setAttribute(PDO::ATTR_ORACLE_NULLS, PDO::NULL_EMPTY_STRING);

    // That's how you can set multiple attributes
}
catch(PDOException $e)
{
    die("Database connection failed: " . $e->getMessage());
}

I hope this helps somebody. :)

down

Anonymous ¶

3 years ago

Note that contrary to most PDO methods, setAttribute does not throw a PDOException when it returns false.

down

steve at websmithery dot co dot uk ¶

7 years ago

For PDO::ATTR_EMULATE_PREPARES, the manual states a boolean value is required. However, when getAttribute() is used to check this value, an integer (1 or 0) is returned rather than true or false.

This means that if you are checking a PDO object is configured as required then

<?php
        // Check emulate prepares is off
        if ($pdo->getAttribute(\PDO::ATTR_EMULATE_PREPARES) !== false) {
            /* do something */
        }
?>

will always 'do something', regardless.

Either

<?php
        // Check emulate prepares is off
        if ($pdo->getAttribute(\PDO::ATTR_EMULATE_PREPARES) != false) {
            /* do something */
        }
?>

or

<?php
        // Check emulate prepares is off
        if ($pdo->getAttribute(\PDO::ATTR_EMULATE_PREPARES) !== 0) {
            /* do something */
        }
?>

is needed instead.

Also worth noting that setAttribute() does, in fact, accept an integer value if you want to be consistent.

down

antoyo ¶

13 years ago

There is also a way to specifie the default fetch mode :

<?php

$connection = new PDO($connection_string);

$connection->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_OBJ);

?>

down

-1

david at datava dot com ¶

6 months ago

Note that in order for
\PDO::ATTR_TIMEOUT
to have any effect, you must set 

\PDO::ATTR_ERRMODE=>\PDO::ERRMODE_EXCEPTION.

If

\PDO::ATTR_ERRMODE=>\PDO::ERRMODE_WARNING

it doesn't appear to do anything.

＋add a note