Doctrineを通してデータベースに接続するには、有効なDSN(Data Source Name)を作らなければなりません。

DoctrineはPDOスタイルと同じようにPEAR DB/MDB2のDSNをサポートします。次のセクションではPEARのDSN形式を扱います。PDOスタイルのDSNの詳しい情報が必要であればPDOのドキュメントを参照してください。

DSNは次の部分で構成されます:

オプションのリスト

DSNは連想配列もしくは文字列のどちらかで提供できます。提供されたDSNの文字列フォーマットの完全な表記は次の通りです:

phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value

大抵のバリアントは許容されます:

phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype:///database
phptype:///database?option=value&anotheroption=anothervalue
phptype(dbsyntax)
phptype

現在サポートされるPDOのデータベースドライバは次の通りです:

サポートされる2番目のDSNは次の通りです

phptype(syntax)://user:pass@protocol(proto_opts)/database

データベース、オプションの値、ユーザー名もしくはパスワードにDSNを区切るために使われる文字が含まれる場合、URIの16進法のエンコーディングを通してエスケープできます:

機能の中にはすべてのデータベースでサポートされないものがあることに十分注意してくださるようお願いします。

Doctrineで新しいデータベース接続を開くのはとても簡単です。PDOを使う場合、新しいPDOオブジェクトを初期化するだけです。

Getting Startedの章で作成したbootstrap.phpファイルを覚えていますか？Doctrineのオートローダーが登録されたコードで、新しい接続をインスタンス化します:

// bootstrap.php

// ...
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);
$conn = Doctrine_Manager::connection($dbh);

Doctrine_Manager::connection()にPDOインスタンスを直に渡すことでDoctrineは接続用のユーザー名とパスワードを認識できません。既存のPDOインスタンスから接続を読み取る方法がないからです。Doctrineがデータベースの作成と削除ができるようにユーザー名とパスワードが必要です。これを切り抜けるには$connオブジェクトでユーザー名とパスワードオプションを直に設定します。

// bootstrap.php

// ...
$conn->setOption('username', $user);
$conn->setOption('password', $password);

データベースへの遅延接続は多くのリソースを節約できます。常に遅延接続を使うことが推奨されるので、実際にデータベース接続を必要とする機会はあまりないでしょう(すなわちDoctrineは必要なときだけデータベースに接続する)。

毎回のリクエストでデータベースの接続が必要ないページキャッシュなどでこの機能がとても役に立ちます。データベースへの接続は負荷の大きいオペレーションであることを覚えておいてください。

下記の例では、Doctrineの新しい接続を作成するときに、データベースへの接続は実際に必要になるまで作成されないことを示しています。

// bootstrap.php

// ...

// この時点でデータベースへの接続は作成されない
$conn = Doctrine_Manager::connection('mysql://username:password@localhost/test');

// 接続が必要な最初のときに、インスタンス化される
// このクエリによって接続が作成される
$conn->execute('SHOW TABLES');

この章の前のセクションを読んだ後で、接続を作成する方法を学ぶことにします。接続のインスタンス化をインクルードするためにブートストラップファイルを修正しましょう。この例ではSQLiteのメモリデータベースを使いますが、望むタイプのデータベース接続は何でも使えます。

bootstrap.phpにデータベース接続を追加すると次のようになります:

/**
 * Bootstrap Doctrine.php、オートローダーを登録して
 * 接続属性を指定する
 */

require_once('../doctrine/branches/1.2/lib/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();

$conn = Doctrine_Manager::connection('sqlite::memory:', 'doctrine');

接続をテストするためにtest.phpスクリプトを修正して小さなテストを実行しましょう。テストスクリプトが変数$connが使えるようになったので接続が動作していることを確認するために小さなテストをセットアップしましょう:

最初に、testテーブルを作りレコードを挿入します:

// test.php

// ...
$conn->export->createTable('test', array('name' => array('type' => 'string')));
$conn->execute('INSERT INTO test (name) VALUES (?)', array('jwage'));

データが挿入されて読み取れることを確認するために作成したばかりのtestテーブルからシンプルなSELECTクエリを実行してみましょう:

// test.php

// ...
$stmt = $conn->prepare('SELECT * FROM test');
$stmt->execute();
$results = $stmt->fetchAll();
print_r($results);

ターミナルからtest.phpを実行すると結果は次の通りです:

$ php test.php
Array
(
    [0] => Array
        (
            [name] => jwage
            [0] => jwage
        )

)

すばらしい！Doctrine接続の基本的なオペレーションを学びました。新しい接続を用意するためにDoctrineのテスト環境を修正しました。次の章の例では接続を使うのでこの環境は必要です。

Configurationの章に移動してDoctrineの属性システムを利用して機能と設定をコントロールする方法を学びます。