Laravel 5.1 Eloquent：利用の開始

イントロダクション

Eloquent ORMはLaravelに含まれている、美しくシンプルなアクティブレコードによるデーター操作の実装です。それぞれのデータベーステーブルは関連する「モデル」と結びついています。モデルによりテーブル中のデータをクエリーできますし、さらに新しいレコードを追加することもできます。

使いはじめる前に確実にcofig/database.phpを設定してください。データベースの詳細はドキュメントで確認してください。

モデル定義

利用を開始するには、まずEloquentモデルを作成しましょう。通常モデルはappディレクトリー下に置きますが、composer.jsonファイルでオートロードするように指定した場所であれば、どこでも自由に設置できます。全てのEloquentモデルは、Illuminate\Database\Eloquent\Modelを拡張する必要があります。

モデルを作成する一番簡単な方法はmake:model Artisanコマンドを使用することです。

php artisan make:model User

モデル作成時にデータベースマイグレーションも生成したければ、--migrationか-mオプションを使ってください。

php artisan make:model User --migration

php artisan make:model User -m

Eloquentモデル規約

ではflightsデータベーステーブルに情報を保存し、取得するために使用するFlightモデルクラスを例として見てください。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    //
}

テーブル名

Flightモデルにどのテーブルを使用するかEloquentに指定していない点に注目してください。他の名前を明示的に指定しない限り、クラス名を複数形の「スネークケース」にしたものがテーブル名として使用されます。今回の例でEloquentはFlightモデルをflightsテーブルに保存します。モデルのtableプロパティを定義し、カスタムテーブル名を指定できます。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルと関連しているテーブル
     *
     * @var string
     */
    protected $table = 'my_flights';
}

主キー

Eloquentは更にテーブルの主キーがidというカラム名であると想定しています。この規約をオーバーライドする場合はprimaryKeyプロパティを定義してください。

タイムスタンプ

デフォルトでEloquentはデータベース上に存在するcreated_at(作成時間)とupdated_at(更新時間)カラムを自動的に更新します。これらのカラムの自動更新をEloquentにしてほしくない場合は、モデルの$timestampsプロパティーをfalseに設定してください。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルのタイムスタンプを更新するかの指示
     *
     * @var bool
     */
    public $timestamps = false;
}

タイムスタンプのフォーマットをカスタマイズする必要があるなら、モデルの$dateFormatプロパティーを設定してください。このプロパティーはデータベースに保存される日付属性のフォーマットを決めるために使用されると同時に、配列やJSONへシリアライズする時にも使われます。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルの日付カラムの保存フォーマット
     *
     * @var string
     */
    protected $dateFormat = 'U';
}

データベース接続

Eloquentモデルはデフォルトとして、アプリケーションに設定されているデフォルトのデータベース接続を使用します。モデルで異なった接続を指定したい場合は、$connectionプロパティーを使用します。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルで使用するコネクション名
     *
     * @var string
     */
    protected $connection = 'connection-name';
}

複数モデルの取得

For example:　モデルと対応するデータベーステーブルを作成したら、データベースからデータを取得できるようになりました。各Eloquentモデルは、対応するテーブルのデータベースへすらすらとクエリーできるようにしてくれるクエリービルダーだと考えてください。例を見てください。

<?php

namespace App\Http\Controllers;

use App\Flight;
use App\Http\Controllers\Controller;

class FlightController extends Controller
{
    /**
     * 利用可能な全フライトの一覧を表示
     *
     * @return Response
     */
    public function index()
    {
        $flights = Flight::all();

        return view('flight.index', ['flights' => $flights]);
    }
}

カラム値に対するアクセス

Eloquentモデルインスタンスを入手したら、モデルのカラム値には対応するプロパティとしてサクセスできます。たとえばクエリーの結果の各Flightインスタンスをループで取得し、nameカラムの値をechoしてみましょう。

foreach ($flights as $flight) {
    echo $flight->name;
}

制約の追加

Eloquentのallメソッドはモデルテーブルの全レコードを結果として返します。Eloquentモデルはクエリービルダーとしても動作しますのでクエリーに制約を付け加えることもでき、結果を取得するにはgetメソッドを使用します。

$flights = App\Flight::where('active', 1)
               ->orderBy('name', 'desc')
               ->take(10)
               ->get();

注目： Eloquentモデルはクエリービルダーですから、クエリービルダーで使用できる全メソッドを確認しておくべきでしょう。Eloquentクエリーでどんなメソッドも使用できます。

コレクション

複数の結果を取得するallやgetのようなEloquentメソッドは、Illuminate\Database\Eloquent\Collectionインスタンスを返します。CollectionクラスはEloquent結果を操作する多くの便利なクラスを提供しています。もちろんこのコレクションは配列のようにループさせることもできます。

foreach ($flights as $flight) {
    echo $flight->name;
}

結果の分割

数千のEloquentレコードを処理する必要がある場合はchunkコマンドを利用してください。chunkメソッドはEloquentモデルの「塊(chunk)」を取得し、引数の「クロージャー」に渡します。chunkメソッドを使えば大きな結果を操作するときのメモリを節約できます。

Flight::chunk(200, function ($flights) {
    foreach ($flights as $flight) {
        //
    }
});

最初の引数には「チャンク（塊）」ごとにいくつのレコードを処理するかを渡します。２番めの引数にはクロージャーを渡し、そのデータベースからの結果をチャンクごとに処理するコードを記述します。

１モデル／集計の取得

もちろん指定したテーブルの全レコードを取得することに加え、findとfirstを使い１レコードだけを取得できます。モデルのコレクションの代わりに、これらのメソッドは１モデルインスタンスを返します。

// 主キーで指定したモデル取得…
$flight = App\Flight::find(1);

// クエリー条件にマッチした最初のレコード取得…
$flight = App\Flight::where('active', 1)->first();

Not Found例外

モデルが見つからない時に例外を投げたい場合もあるでしょう。これは特にルートやコントローラーの中で便利です。findOrFailメソッドとクエリーの最初の結果を取得するfirstOrFailメソッドは、該当するレコードが見つからない場合にIlluminate\Database\Eloquent\ModelNotFoundException例外を投げます。

$model = App\Flight::findOrFail(1);

$model = App\Flight::where('legs', '>', 100)->firstOrFail();

この例外がキャッチされないと自動的に404HTTPレスポンスがユーザーに送り返されますので、これらのメソッドを使用すればわざわざ明確に404レスポンスを返すコードを書く必要はありません。

Route::get('/api/flights/{id}', function ($id) {
    return App\Flight::findOrFail($id);
});

集計の取得

もちろんクエリービルダーが提供しているcount、sum、maxやその他の集計関数を使用することもできます。これらのメソッドは完全なモデルインスタンスの代わりに最適なスカラー値を返します。

$count = App\Flight::where('active', 1)->count();

$max = App\Flight::where('active', 1)->max('price');

モデルの追加と更新

基本の追加

モデルから新しいレコードを作成するには新しいインスタンスを作成し、saveメソッドを呼び出します。

<?php

namespace App\Http\Controllers;

use App\Flight;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class FlightController extends Controller
{
    /**
     * 新しいflightインスタンスの生成
     *
     * @param  Request  $request
     * @return Response
     */
    public function store(Request $request)
    {
        // リクエストのバリデーション…

        $flight = new Flight;

        $flight->name = $request->name;

        $flight->save();
    }
}

この例では、やって来たHTTPリクエストのnameパラメーターをApp\Flightモデルインスタンスのname属性に代入しています。saveメソッドが呼ばれると新しいレコードがデータベースに挿入されます。saveが呼び出された時にcreated_atとupdated_atタイムスタンプは自動的に設定されますので、わざわざ設定する必要はありません。

基本の更新

saveメソッドはデータベースで既に存在するモデルを更新するためにも使用されます。モデルを更新するにはまず取得する必要があり、更新したい属性をセットしてそれからsaveメソッドを呼び出します。この場合もupdated_atタイムスタンプは自動的に更新されますので、値を指定する手間はかかりません。

$flight = App\Flight::find(1);

$flight->name = '新しいフライト名';

$flight->save();

指定したクエリーに一致する複数のモデルに対し更新することもできます。以下の例ではactiveで到着地(destination)がSan Diegoの全フライトに遅延(delayed)のマークを付けています。

App\Flight::where('active', 1)
          ->where('destination', 'San Diego')
          ->update(['delayed' => 1]);

updataメソッドは更新したいカラムと値の配列を受け取ります。

複数代入

一行だけで新しいモデルを保存するにはcreateメソッドが利用できます。挿入されたモデルインスタンスがメソッドから返されます。しかしこれを利用する前にEloquentモデルを複数代入から保護するために、モデルへfillableかguarded属性のどちらかを設定する必要があります。

複数代入の脆弱性はリクエストを通じて予期しないHTTPパラメーターが送られた時に起き、そのパラメーターはデータベースのカラムを予期しないように変更してしまうでしょう。たとえば悪意のあるユーザーがHTTPパラメーターでis_adminパラメーターを送り、それがモデルのcreateメソッドに対してマップされると、そのユーザーは自分自身を管理者(administrator)に昇格できるのです。

ですから最初に複数代入したいモデルの属性を指定してください。モデルの$fillableプロパティで指定できます。たとえば、Flightモデルの複数代入でname属性のみ使いたい場合です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 複数代入する属性
     *
     * @var array
     */
    protected $fillable = ['name'];
}

複数代入する属性を指定したら、新しいレコードをデータベースに挿入するためにcreateが利用できます。createメソッドは保存したモデルインスタンスを返します。

$flight = App\Flight::create(['name' => 'Flight 10']);

$fillableが複数代入時における属性の「ホワイトリスト」として動作する一方、$guardedの使用を選ぶことができます。$guardedプロパティーは複数代入したくない属性の配列です。配列に含まれない他の属性は全部複数台入可能です。そのため$guardedは「ブラックリスト」として働きます。もちろん$fillableか$guardedのどちらか一方を使用してください。両方一度には使えません。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 複数代入しない属性
     *
     * @var array
     */
    protected $guarded = ['price'];
}

この例ではprice以外の全属性で複数代入ができます。

他の生成メソッド

他にも属性の複数代入可能な生成メソッドが２つあります。firstOrCreateとfirstOrNewです。firstOrCreateメソッドは指定されたカラム／値ペアでデータベースレコードを見つけようします。モデルがデータベースで見つからない場合、指定された属性でレコードが挿入されます。

firstOrNewメソッドもfirstOrCreateのように指定された属性にマッチするデータベースのレコードを見つけようとします。しかしモデルが見つからない場合、新しいモデルインスタンスが返されます。firstOrNewが返すモデルはデータベースに保存されていないことに注目です。保存するにはsaveメソッドを呼び出す必要があります。

// 属性のフライトを取得するか、存在しなければ作成する…
$flight = App\Flight::firstOrCreate(['name' => 'Flight 10']);

// 属性のフライトか、存在しなければ新しいインスタンスを取得する…
$flight = App\Flight::firstOrNew(['name' => 'Flight 10']);

モデル削除

モデルを削除するには、モデルに対しdeleteメソッドを呼び出します。

$flight = App\Flight::find(1);

$flight->delete();

キーによる既存モデルの削除

上記の例ではdeleteメソッドを呼び出す前にデータベースからモデルを取得しています。しかしモデルの主キーが分かっている場合なら、モデルを取得せずに削除できます。destroyメソッドを呼び出してください。

App\Flight::destroy(1);

App\Flight::destroy([1, 2, 3]);

App\Flight::destroy(1, 2, 3);

クエリーによるモデル削除

もちろん一連のモデルをクエリーを実行し削除することもできます。次の例はactiveではない印を付けられたフライトを削除しています。

$deletedRows = App\Flight::where('active', 0)->delete();

ソフトデリート

実際にデータベースからレコードを削除する方法に加え、Eloquentはモデルの「ソフトデリート」も行えます。モデルがソフトデリートされても実際にはデータベースのレコードから削除されません。代わりにそのモデルにdeleted_at属性がセットされ、データベースへ書き戻されます。モデルのdeleted_atの値がNULLでない場合、ソフトデリートされています。モデルのソフトでリートを有効にするにはモデルにIlluminate\Database\Eloquent\SoftDeletesトレイトを使い、deleted_atカラムを$datesプロパティに追加します。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Flight extends Model
{
    use SoftDeletes;

    /**
     * 日付へキャストする属性
     *
     * @var array
     */
    protected $dates = ['deleted_at'];
}

もちろんデータベーステーブルにもdeleted_atカラムを追加する必要があります。Laravelスキーマビルダーにはこのカラムを作成するメソッドが存在しています。

Schema::table('flights', function ($table) {
    $table->softDeletes();
});

これでモデルに対しdeleteメソッドを使用すれば、deleted_atカラムに現在の時間がセットされます。ソフトデリートされたモデルに対しクエリーがあっても、削除済みのモデルはクエリー結果に含まれません。

指定されたモデルインスタンスがソフトデリートされているかを確認するには、trashedメソッドを使います。

if ($flight->trashed()) {
    //
}

ソフトデリート済みモデルのクエリー

ソフトデリート済みモデルも含める

前述のようにソフトデリートされたモデルは自動的にクエリーの結果から除外されます。しかし結果にソフトデリート済みのモデルを含めるように強制したい場合は、クエリーにwithTrashedメソッドを使ってください。

$flights = App\Flight::withTrashed()
                ->where('account_id', 1)
                ->get();

withTrashedメソッドはリレーションのクエリーにも使えます。

$flight->history()->withTrashed()->get();

WHERE節での注意

ソフトデリート対応モデルに対し、orWhere節をクエリーに追加する時には、常に上級のWHERE節指定をWHERE節の論理グループに対して使用してください。例を見てください。

User::where(function($query) {
        $query->where('name', '=', 'John')
              ->orWhere('votes', '>', 100);
        })
        ->get();

これにより、以下のSQLが生成されます。

select * from `users` where `users`.`deleted_at` is null and (`name` = 'John' or `votes` > 100)

orWhere節をグループに対して使用しないと、以下のようにソフトデリートしたレコードを含むようなSQLを生成します。

select * from `users` where `users`.`deleted_at` is null and `name` = 'John' or `votes` > 100

ソフトデリート済みモデルのみの取得

onlyTrashedメソッドによりソフトデリート済みのモデルのみを取得できます。

$flights = App\Flight::onlyTrashed()
                ->where('airline_id', 1)
                ->get();

ソフトデリートの解除

時にはソフトデリート済みのモデルを「未削除」に戻したい場合も起きます。ソフトデリート済みモデルを有効な状態に戻すには、そのモデルインスタンスに対しrestoreメソッドを使ってください。

$flight->restore();

複数のモデルを手っ取り早く未削除に戻すため、クエリーにrestoreメソッドを使うこともできます。

App\Flight::withTrashed()
        ->where('airline_id', 1)
        ->restore();

withTrashedメソッドと同様、restoreメソッドはリレーションに対しても使用できます。

$flight->history()->restore();

モデルの完全削除

データベースからモデルを本当に削除する場合もあるでしょう。データベースからソフトデリート済みモデルを永久に削除するにはforceDeleteメソッドを使います。

// １モデルを完全に削除する…
$flight->forceDelete();

// 関係するモデルを全部完全に削除する…
$flight->history()->forceDelete();

クエリースコープ

スコープはアプリケーションのどこでも簡単に共通の制約定義を再利用できるようにします。たとえば「人気がある(pupular)」と思われるユーザーを全員を頻繁に必要だとしましょう。スコープを定義するにはEloqunetモデルのメソッド名にscopeプレフィックスを付けるだけです。

スコープはいつもクエリービルダーインスタンスを返します。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 人気のあるユーザーだけをクエリーするスコープ
     *
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopePopular($query)
    {
        return $query->where('votes', '>', 100);
    }

    /**
     * アクティブなユーザーだけをクエリーするスコープ
     *
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeActive($query)
    {
        return $query->where('active', 1);
    }
}

クエリースコープの使用

スコープが定義できたらモデルのクエリー時にスコープメソッドを呼び出せます。しかしメソッドを呼び出すときにscopeプレフィックスを付ける必要はありません。様々なスコープをチェーンでつなぎ呼び出すこともできます。例を見てください。

$users = App\User::popular()->active()->orderBy('created_at')->get();

動的スコープ

引数を受け取るスコープを定義したい場合もあるでしょう。スコープにパラメーターを付けるだけです。スコープパラメーターは$query引数の後に定義しする必要があります。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 指定したタイプのユーザーだけを含むクエリーのスコープ
     *
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeOfType($query, $type)
    {
        return $query->where('type', $type);
    }
}

これでスコープを呼び出すときにパラメーターを渡せます。

$users = App\User::ofType('admin')->get();

イベント

Eloquentモデルは多くのイベントを発行します。creating、created、updating、updated、saving、saved、deleting、deleted、restoring、restoredのメソッドを利用し、モデルのライフサイクルの様々な時点をフックすることができます。イベントにより特定のモデルクラスが保存されたりアップデートされたりするたび、簡単にコードを実行できるようになります。

基本的な使用法

いつでも新しいアイテムが最初に保存される場合にcreatingとcreatedイベントが発行されます。新しくないアイテムにsaveメソッドが呼び出されるとupdatingとupdatedイベントが発行されます。どちらの場合にもsavingとsavedイベントは発行されます。

例としてサービスプロバイダーでEloquentイベントリスナーを定義してみましょう。イベントリスナーの中で指定されたモデルに対しisValidメソッドを呼び出し、モデルが有効でなければfalseが返されます。Eloquentイベントリスナーがfalseを返すとsave／update操作はキャンセルされます。

<?php

namespace App\Providers;

use App\User;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 全アプリケーションサービスの初期処理
     *
     * @return void
     */
    public function boot()
    {
        User::creating(function ($user) {
            if ( ! $user->isValid()) {
                return false;
            }
        });
    }

    /**
     * サービスプロバイダーの登録
     *
     * @return void
     */
    public function register()
    {
        //
    }
}