diff --git a/docs/guide-ja/images/start-country-list.png b/docs/guide-ja/images/start-country-list.png new file mode 100644 index 0000000..6994da2 Binary files /dev/null and b/docs/guide-ja/images/start-country-list.png differ diff --git a/docs/guide-ja/start-databases.md b/docs/guide-ja/start-databases.md new file mode 100644 index 0000000..5e955cc --- /dev/null +++ b/docs/guide-ja/start-databases.md @@ -0,0 +1,261 @@ +データベースを扱う +================== + +この節では、`country` という名前のデータベーステーブルから読み出した国データを表示する新しいページの作り方を説明します。 +この目的を達するために、データベース接続を設定し、[アクティブレコード](db-active-record.md) クラスを作成し、 +[アクション](structure-controllers.md) を定義し、そして [ビュー](structure-views.md) を作成します。 + +このチュートリアルを通じて、次のことをする方法を学びます: + +* DB 接続を設定する +* アクティブレコードのクラスを定義する +* アクティブレコードのクラスを使ってデータを検索する +* 改ページを伴う方法でビューにデータを表示する + +この節を完了するためには、データベースを使うことについて基本的な知識と経験が無ければならないことに注意してください。 +具体的に言えば、DB クライアントツールを用いてデータベースを作成する方法と、SQL 文を実行する方法を知っていなければなりません。 + + +データベースを準備する +---------------------- + + +まず初めに、`yii2basic` という名前のデータベースを作成してください。このデータベースからアプリケーションにデータを読み出すことになります。 +作成するデータベースは、SQLite、MySQL、PosttreSQL、MSSQL または Oracle から選んでください。 +Yii は多数のデータベース製品に対するサポートを組み込みで持っています。 +以下の説明では、話を単純にするために、MySQL を前提とします。 + +次に、データベースに `country` という名前のテーブルを作り、いくつかのサンプルデータを挿入します。 +そうするために、次の SQL 文を実行することが出来ます: + +```sql +CREATE TABLE `country` ( + `code` CHAR(2) NOT NULL PRIMARY KEY, + `name` CHAR(52) NOT NULL, + `population` INT(11) NOT NULL DEFAULT '0' +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +INSERT INTO `country` VALUES ('AU','Australia',18886000); +INSERT INTO `country` VALUES ('BR','Brazil',170115000); +INSERT INTO `country` VALUES ('CA','Canada',1147000); +INSERT INTO `country` VALUES ('CN','China',1277558000); +INSERT INTO `country` VALUES ('DE','Germany',82164700); +INSERT INTO `country` VALUES ('FR','France',59225700); +INSERT INTO `country` VALUES ('GB','United Kingdom',59623400); +INSERT INTO `country` VALUES ('IN','India',1013662000); +INSERT INTO `country` VALUES ('RU','Russia',146934000); +INSERT INTO `country` VALUES ('US','United States',278357000); +``` + +この時点で、あなたは `yii2basic` という名前のデータベースを持ち、その中に三つのカラムを持つ `country` というテーブルを持っています。 +そして、`country` テーブルは、10 行のデータを持っています。 + + +DB 接続を設定する +----------------- + +先に進む前に、[PDO](http://www.php.net/manual/en/book.pdo.php) PHP 拡張および使用しているデータベースの PDO ドライバ +(例えば、MySQL のための `pdo_mysql`) の両方をインストール済みであることを確認してください。 +アプリケーションがリレーショナルデータベースを使う場合、これは基本的な必要条件です。 + +これらがインストール済みなら、`config/db.php` というファイルを開いて、あなたのデータベースに適合するように +パラメータを変更してください。既定値では、このファイルは下記の記述を含んでいます: + +```php + 'yii\db\Connection', + 'dsn' => 'mysql:host=localhost;dbname=yii2basic', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', +]; +``` + +この `config/db.php` というファイルは典型的なファイルベースの [設定](concept-configurations.md) ツールです。 +この設定ファイルが [[yii\db\Connection]] インスタンスの作成と初期化に必要なパラメータを規定します。そして、 +[[yii\db\Connection]] インスタンスを通じて、背後のデータベースに対して SQL クエリを実行することが出来るようになります。 + +上記のようにして設定された DB 接続は、アプリケーションコードの中で `Yii::$app->db` という式でアクセスすることが出来ます。 + +> Info|情報: `config/db.php` は、メインのアプリケーション設定ファイルである `config/web.php` にインクルードされます。 + この `config/web.php` が [アプリケーション](structure-applications.md) インスタンスが初期化される仕方を規定します。 + 更なる情報については、[設定](concept-configurations.md) の節を参照してください。 + + +アクティブレコードを作成する +---------------------------- + +`country` テーブルの中のデータを表現し取得するために、[アクティブレコード](db-active-record.md) から派生した +`Country` という名前のクラスを作成し、それを `models/Country.php` というファイルに保存します。 + +```php + Info|情報: クラス名とテーブル名を直接に合致させることが出来ない場合は、[[yii\db\ActiveRecord::tableName()]] メソッドをオーバーライドして、関連づけられたテーブル名を明示的に規定することが出来ます。 + +`Country` クラスを使うことによって、以下のコード断片で示すように、`country` テーブルの中のデータを簡単に操作することが出来ます: + +```php +use app\models\Country; + +// country テーブルから全ての行を取得して "name" 順に並べる +$countries = Country::find()->orderBy('name')->all(); + +// プライマリキーが "US" である行を取得する +$country = Country::findOne('US'); + +// "United States" を表示する +echo $country->name; + +// 国名を "U.S.A." に修正してデータベースに保存する +$country->name = 'U.S.A.'; +$country->save(); +``` + +> Info|情報: アクティブレコードは、オブジェクト指向の流儀でデータベースのデータにアクセスし、操作する強力な方法です。 +[Active Record](db-active-record.md) の節で、更に詳細な情報を得ることが出来ます。 +もう一つの方法として、[データアクセスオブジェクト(DAO)](db-dao.md) と呼ばれる、より低レベルなデータアクセス方法を使って +データベースを操作することも出来ます。 + + +アクションを作成する +-------------------- + +国データをエンドユーザに見えるようにするために、新しいアクションを作成する必要があります。 +これまでの節でしたように `site` コントローラの中に新しいアクションを置くのではなく、国データに関係する全てのアクションに +限定した新しいコントローラを作成する方が理にかなうでしょう。この新しいコントローラを `CountryController` と名付けます。 +そして、下記に示すように、`index` アクションをその中に作成します。 + + +```php + 5, + 'totalCount' => $query->count(), + ]); + + $countries = $query->orderBy('name') + ->offset($pagination->offset) + ->limit($pagination->limit) + ->all(); + + return $this->render('index', [ + 'countries' => $countries, + 'pagination' => $pagination, + ]); + } +} +``` + +上記のコードを `controllers/CountryController.php` というファイルに保存します。 + +`index` アクションは `Country::find()` を呼び出します。 +このアクティブレコードのメソッドは DB クエリを構築して、`country` テーブルから全てのデータを読み出します。 +一回のリクエストで返される国の数を制限するために、クエリは [[yii\data\Pagination]] オブジェクトの助けを借りてページ付けされます。 +`Pagination` オブジェクトは二つの目的に奉仕します: + +* クエリによって表現される SQL 文に `offset` 句と `limit` 句をセットして、一度に一ページ分のデータだけ (1ページ最大5行)を返すようにします。 +* 次の項で説明されるように、一連のページボタンからなるページャをビューに表示するために使われます。 + +コードの最後で、`index` アクションは `index` と言う名前のビューを表示していますが、このとき、国データはもちろん、そのページ付け情報もビューに渡されます。 + + +ビューを作成する +---------------- + +最初に、`views` ディレクトリの下に `country` という名前のサブディレクトリを作ってください。 +このフォルダが `country` コントローラによって表示される全てのビューを保持するのに使われます。 +`views/country` ディレクトリの中に、下記のコードを含む `index.php` という名前のファイルを作成します: + +```php + +