LaravelのEloquentORMの基本から具体的な使い方（モデルを使ったDB操作）

テーブルの指定

このモデルに紐づけるテーブル名を設定します。

基本的には、Laravelがクラス名に紐づくテーブル名を自動的に引いてきてくれるので、クラス名とテーブル名が同じ名前の場合は指定しなくてもOKです。例えば、今回使用しているFrameworkクラスに対して、紐づけるテーブルはframeworksテーブルなので、この場合は設定なくても動作します。

ちなみに、テーブル名がスネークケースの場合は、パスカルケースでのクラス名で一致します。

• テーブル名「php_frameworks」＝クラス「PhpFramework」
• テーブル名「sample_name_lists」＝クラス「SampleNameList」

モデルクラス名が単数形なのに対して、テーブル名は複数形になる関係性です。この関係性が成立する場合に、Laravelではモデルから自動でテーブルを解決してくれます。

もし、上記ルールに沿わない場合や、作成したテーブルとクラスの名前が全く違う場合は、以下のようにしてメンバ変数 $table にテーブル名をセットします。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // テーブル名の指定
    protected $table = 'web_frameworks';
}

主キーの指定

Eloquentでのモデル実装時は、暗黙で「主キー＝カラム名id」として処理を行います。

もし主キーのカラム名が「id」以外の場合は、以下のようにメンバ変数 $primaryKey に主キーのカラム名をセットします。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // 主キーの指定
    protected $primaryKey = 'framework_id';
}

ちなみにEloquentでは、暗黙で主キー＝自動増分（AUTO_INCREMENT）であるとして処理されます。併せて、デフォルトでは主キーは数値型であるという想定で処理が行われます。

上記ルールに沿わない場合は、以下で設定を変更できます。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // 自動増分ではない場合
    public $incrementing = false;

    // 主キーが数値型ではない場合
    protected $keyType = 'string';
}

タイムスタンプの指定

Eloquentでは、暗黙で created_at(作成日時)カラムと updated_at(更新日時)カラムがある前提でそれらを自動的に更新しようとします。

自動更新をOFFにしたい場合は、メンバ変数 $timestamps に false を指定します。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // created_atとupdated_atの自動更新をOFFにする
    public $timestamps = false;
}

タイムスタンプはデフォルトでtimestamp型として日時を挿入しますが、フォーマットを変更する事も可能です。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // 日付カラムのフォーマットを指定する
    protected $dateFormat = 'U';
}

上記の場合は、UNIX時間で挿入されます。

ちなみに、そもそも作成日時と更新日時のカラムがcreated_atとupdated_atではない場合もあります。そんな場合は以下のように定数を設定する事でカラムを指定できます。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // 作成日時カラムの指定
    const CREATED_AT = 'create_dt';

    // 更新日時カラムの指定
    const UPDATED_AT = 'update_dt';
}

データベースの指定

Eloquentはデフォルトでデータベースの設定ファイルから、defaultプロパティの値を見てそれを用いて接続を行いに行きます。

laravel/config/database.php

'default' => env('DB_CONNECTION', 'mysql'),

laravel/.env

DB_CONNECTION=mysql

接続先を変更したい場合は、メンバ変数 $connection にコネクション名を設定します。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // データベースコネクション先の指定
    protected $connection = 'redis';
}

デフォルト値の指定

インサート時のデフォルト値を指定したい場合は$attributesを設定します。

laravel/app/Models/Framework.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    protected $attributes = [
        'category' => 'PHP',
    ];
}

上記の場合は、インサート時にcategoryフィールドへの値がなければ「PHP」という値が入ります。

全てのデータを取得する

まずは、全てのデータを取得します。条件を一切つけずに全てのデータを取得するには、all()メソッドを使います。

// 全てのデータを取得する
$data = Framework::all();

結果データはコレクションオブジェクトで返却され、ループで取り出す事が出来ます。

$data = Framework::all();

$item = [];
foreach ($data as $d) {
    $item = [
        'id' => $d->id,
        'name' => $d->name,
        'category' => $d->category,
    ];

    // print_r($item);
    // => Array
    // (
    //     [id] => 1
    //     [name] => Laravel
    //     [category] => PHP
    // )
}

これは条件を指定した場合も同様です。

条件を指定する

条件を指定する場合は、クエリビルダと同様の記述で指定が可能です。

例えば、PHPのフレームワークのみを取得する場合は、以下のように記述します。

$data = Framework::where('category', 'PHP')->get();

第一引数には条件付けを行うフィールド、第二引数には条件となる値を渡します。この場合は、暗黙的に＝「イコール」として処理されます。

条件がイコールではない場合は、第二引数に演算子を渡し、第三引数に条件となる値を渡します。

// id が 10 未満のデータを取得する
$data = Framework::where('id', '<',  10)->get();

ちなみに分割処理や集計に関してもクエリビルダと同様に実装できます。 （条件のバリエーションについては、Laravelのクエリビルダ記法まとめにまとめてあります。）

また、Eloquent独自のメソッドとして、主キーを指定してデータを取得する場合は、find()メソッドが使えます。

// id = 1 のレコードを取得する
$data = Framework::find(1);

save()

Eloquentでテーブルに新しいレコードを挿入する場合は、save()メソッドが使えます。

public function index()
{
    // 1件のレコードを挿入する
    $fw = new Framework();
    $fw->name = "D3";
    $fw->category = "Javascript";
    $fw->save();
}

実行後、MySQLを確認するとデータが挿入されている事が確認できます。

mysql> SELECT * FROM `frameworks` ORDER BY id DESC LIMIT 1;
+----+------------+------+---------------------+---------------------+
| id | category   | name | created_at          | updated_at          |
+----+------------+------+---------------------+---------------------+
| 24 | Javascript | D3   | 2019-08-11 02:35:31 | 2019-08-11 02:35:31 |
+----+------------+------+---------------------+---------------------+
1 row in set (0.00 sec)

作成日時と更新日時も自動で更新されています。

create()

登録できるカラムに制約を設けた形でレコード挿入（１件のみ）も行えます。その場合にはcreate()メソッドを使います。

クエリを書く前に、モデルへレコード挿入を許可するカラムを指定します。

laravel/app/Models/Framework.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    // 登録を許可するフィールド
    protected $fillable = ['name', 'category'];
}

ここで許可しないカラムへはデータを挿入できません。

逆に、許可しない設定もできます。

// 登録を許可しないカラム
protected $guarded = ['admin'];

ここで禁止しないカラムはデータ挿入を許可する事になります。

全てを許可する場合は、以下のようにも記述できます。

protected $guarded = [];

許可する$fillableと許可しない$guardedは、どちらか一方のみを設定できます。両方は設定できません。

これらの設定を行ったら、create()メソッドでレコード挿入を行えます。

Framework::create([
    'name' => 'Ice Framework',
    'category' => 'PHP'
]);

firstOrCreate

firstOrCreate()メソッドは、送信したカラム/値を持つレコードが存在するかをまず探します。 そして該当するレコードが無かった場合は、レコード１件が挿入されます。 逆に、該当するレコードが存在する場合はインサートは行われず、そのレコードが返されます。

$data = Framework::firstOrCreate(
            ['name' => 'Laravel'],
            ['category' => 'PHP']
        );

このメソッドの注意点として、上記のように複数のカラム/値ペアをセットする場合ですが、レコードに値が存在するかどうかを評価するのは先頭のカラム/値ペアのみになります。 従って、先頭のカラム/値ペアがレコードに存在していなければ、他のカラム/値ペアを合わせてインサートが行われます。

もう少し噛み砕くと、上記の場合は以下の条件で動作する事になります。

• 「name」に「Laravel」という値を持つレコードが無ければ、その時点でインサートが走ります。
• 「name」に「Laravel」という値を持つレコードが存在する場合は、「category」に未知の値がある場合でもインサートは行われず、「name=Laravel」に該当するレコード（の１件目）が返却されます。

firstOrNew

firstOrNew()メソッドは、送信したカラム/値を持つレコードが存在するかをまず探し、存在すればそのモデルインスタンスを返しますが、存在しなかった場合は、送信した値で新しいモデルインスタンスが生成され、返却されます。つまり、レコードは挿入されません。

$data = Framework::firstOrNew(
            ['name' => 'Symfony'],
            ['category' => 'PHP']
        );

戻り値として受け取った新しいモデルインスタンスを保存する場合は、そのモデルインスタンスに対してsave()メソッドを発行します。

$data = Framework::firstOrNew(
            ['name' => 'Kohana'],
            ['category' => 'PHP']
        );

// 保存
$data->save();

ちなみにこの時、レコードが無かった場合はInsertとなり、レコードが存在していた場合はUpdateとなります。

updateOrCreate

updateOrCreate()メソッドは、渡したカラム/値ペアに合致するレコードがあるかを探し、あれば更新を行い、なければ新しいレコードが挿入されます。

Framework::updateOrCreate(
    ['name' => 'React', 'category' => 'JS'],
    ['category' => 'Javascript']
);

このメソッドのポイントは、第一引数に渡した配列内のカラム/値ペアでレコードの存在を確認し、存在していれば第二引数の配列内のカラム/値ペアで更新を行います。

レコードが存在していない場合は、これらの値を以てレコード挿入が行われます。

delete()

通常のモデル削除であれば、delete()メソッドがあります。

// id=29 のレコードを取得
$model = Framework::find(29);

// 削除
$model->delete();

Eloquentではモデルベースで操作が行われるので、delete()メソッドを用いる場合は、削除するレコードを指定し削除を行うのではなく、削除するレコードのモデルインスタンスを一旦取得した後にdelete()メソッドを叩くという流れになっている点がポイントです。

と言いつつも、メソッドチェーンで一撃削除も出来ます。

// 条件式で複数取得＋deleteメソッドをチェインして削除
Framework::where('category', 'JS')->delete();

destroy()

主キーが判明している場合は、destroy()メソッドでダイレクトにレコードを削除する事が出来ます。

// １件の削除
Framework::destroy(27);

// 複数件まとめて削除 - 1（配列で渡す）
Framework::destroy([23, 25, 26]);

// 複数件まとめて削除 - 2（１つずつ渡す）
Framework::destroy(20, 21, 22);

上記例では３パターンで記述していますが、一番上は一件のみの削除、あとの２つは複数件のレコードをまとめて削除するパターンの書式です。

あくまでも、主キーを渡す事で削除が行えるというのがこのメソッドのポイントです。

グローバルスコープ

グローバルスコープは、前述した通り全体にがっつりクエリスコープを仕込みます。ではスコープを作成します。

laravel/app 配下に Scopes ディレクトリを作成し、CategoryScope.php を作成します。

<?php

namespace App\Scopes;

use Illuminate\Database\Eloquent\Scope;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;

class CategoryScope
{
    /**
     * @param  \Illuminate\Database\Eloquent\Builder  $builder
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        // category は PHP のみ
        $builder->where('category', 'PHP');
    }
}

グローバルスコープを定義します。

laravel/app/Scopes/CategoryScope.php

<?php

namespace App\Scopes;

use Illuminate\Database\Eloquent\Scope;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;

class CategoryScope implements Scope
{
    /**
     * @param Builder $builder
     * @param Model $model
     */
    public function apply(Builder $builder, Model $model)
    {
        // category は PHP のみ
        $builder->where('category', 'PHP');
    }
}

categoryカラムがPHPであるもののみを取得するように定義しました。

次に、対象のモデルクラスへスコープを登録します。

laravel/app/Models/Framework.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use App\Scopes\CategoryScope; // 追加

class Framework extends Model
{
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope(new CategoryScope);
    }
}

これで設定は完了しました。コントローラから取得してみると、条件指定を行わなくても、categoryがPHPのものしか取得されなくなります。

$data = Framework::all();
// =>  SELECT * FROM `frameworks` WHERE `category` = 'PHP';

// グローバルスコープをスキップ
$data = Framework::withoutGlobalScope(\App\Scopes\CategoryScope::class)->get();

// 複数のグローバルスコープをスキップ
$data = Framework::withoutGlobalScopes([
    \App\Scopes\OneScope::class, \App\Scopes\TwoScope::class
])->get();

// 全てのグローバルスコープをスキップ
$data = Framework::withoutGlobalScopes()->get();

ローカルスコープ

ローカルスコープは、予め定義しておいたある条件を任意のタイミングでスポット的に使用できるものです。つまり、前もって条件を定義しておき、必要な時にそれらを当てて適用する事ができます。

ローカルスコープも、モデルに定義します。

laravel/app/Models/Framework.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Framework extends Model
{
    /**
     * categoryが「PHP」を含むものとするクエリスコープ
     * @param $query
     * @return mixed
     */
    public function scopeCategoryInPhp($query)
    {
        return $query->orWhereIn('category', ['PHP']);
    }

    /**
     * categoryが「Python」を含むものとするクエリスコープ
     * @param $query
     * @return mixed
     */
    public function scopeCategoryInPython($query)
    {
        return $query->orWhereIn('category', ['Python']);
    }
}

カテゴリがPHPのものとするスコープと、カテゴリがPythonのものとするスコープを記述しました。

これで定義は完了です。使用してみます。

// CategoryInPhpスコープを適用する
$data = Framework::CategoryInPhp()->get();

// CategoryInPhpスコープとCategoryInPythonスコープの両方を適用する
$data = Framework::CategoryInPhp()->CategoryInPython()->get();

これでスコープに定義した条件が適用されます。ちなみにスコープをチェインして複数適用させる事もできます。

スコープに引数を渡したい場合は、以下のように定義します。

laravel/app/Models/Framework.php

/**
 * 任意のカテゴリを含むものとするクエリスコープ
 * @param $query
 * @param array $types
 * @return mixed
 */
public function scopeCategoryInSomething($query, array $types)
{
    return $query->orWhereIn('category', $types);
}

あとはスコープメソッドに引数を渡せばOKです。

// 取得したいカテゴリを配列で渡す
$data = Framework::CategoryInSomething(['PHP', 'Javascript'])->get();

オブザーバクラス

イベントを登録する時に、例えばデータを保存した時のsavedイベントにはSlack通知・メール配信・ログファイル書き込み・別のテーブルへのログ書き込み…など、登録するイベントがたくさんある場合があります。しかもそれが別のイベントの時も…となると結構な数です。

そんな場合は、オブザーバクラスを作成する事で、イベントの登録をまとめる事が出来ます。

laravel/app 配下に Observersディレクトリを作成し、そこへFrameworksObserver.phpを作成します。

laravel
├─ app
│   ├─ Observers
│   │   └─ FrameworkObserver.php

オブザーバクラスを定義します。

laravel/app/Observers/FrameworksObserver.php

<?php

namespace App\Observers;

use App\Models\Framework;
use Illuminate\Support\Facades\Log;
use App\Events\AccessDetection;

class FrameworkObserver
{
    /**
     * モデル取得イベントのリッスン
     *
     * @param  \App\Models\Framework  $Framework
     * @return void
     */
    public function retrieved(Framework $Framework)
    {
        // ログの書き込み
        Log::debug($Framework->name);
        // イベント発火
        event(new AccessDetection(str_random(100)));
    }

    /**
     * 作成イベントのリッスン
     *
     * @param  \App\Models\Framework  $Framework
     * @return void
     */
    public function created(Framework $Framework)
    {
        //
    }

    /**
     * 作成イベントのリッスン
     *
     * @param  \App\Models\Framework  $Framework
     * @return void
     */
    public function updated(Framework $Framework)
    {
        //
    }

    /**
     * 削除イベントのリッスン
     *
     * @param  \App\Models\Framework  $Framework
     * @return void
     */
    public function deleting(Framework $Framework)
    {
        //
    }
}

上記のようにして、各イベントメソッドに対して処理を定義していく事でそのイベントに対する処理を行う事が出来ます。ログの書き込みなど、必ずイベント＆リスナでなくてはいけないという事はなく、自由に実装できます。