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

テーブルの指定

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

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

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

• テーブル名「php_frameworks」＝クラス「PhpFrameworks」
• テーブル名「sample_name_list」＝クラス「SampleNameList」

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

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

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

主キーの指定

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

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

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Frameworks extends Model
{
    // テーブル名の指定
    protected $table = 'web_framework';

    // 主キーの指定
    protected $primaryKey = 'framework_id';
}

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

「そんな事聞いてないよ！」という状況の場合は以下のようにして、そんな先人が決めつけた「まあ普通はそうでしょ」というルールをぶち破れます。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Frameworks extends Model
{
    // テーブル名の指定
    protected $table = 'web_framework';

    // 主キーの指定
    protected $primaryKey = 'framework_id';

    // 自動増分ではない場合
    public $incrementing = false;

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

タイムスタンプの指定

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

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

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

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

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

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

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

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

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

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

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

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

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

    // 作成日時カラムの指定
    const CREATED_AT = 'create_date';
    
    // 更新日時カラムの指定
    const UPDATED_AT = 'update_date';
}

データベースの指定

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

laravel/config/database.php

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

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

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

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

全てのデータを取得する

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

// 全てのデータを取得する
$data = $this->frameworks->all();

結果データコレクションはループで回して取り出す事が出来ます。

$data = $this->frameworks->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 = $this->frameworks
        ->where('category', 'PHP')
        ->get();

Laravelのクエリビルダについては
Laravelのクエリビルダ記法まとめ
を参照してください。

分割処理や集計に関してもクエリビルダと同様に実装できます。

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

// id:1 のレコードを取得する
$this->frameworks->find(1);

save()

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

public function index()
{
    $this->frameworks->name = "D3";
    $this->frameworks->category = "Javascript";
    $this->frameworks->save();
}

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

mysql> select * from frameworks;
+----+------------+----------------+---------------------+---------------------+
| id | category   | name           | created_at          | updated_at          |
+----+------------+----------------+---------------------+---------------------+
| 24 | Javascript | D3             | 2018-06-06 00:13:49 | 2018-06-06 00:13:49 |
+----+------------+----------------+---------------------+---------------------+

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

create()

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

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

class Frameworks extends Model
{
    // 登録を許可するカラム
    protected $fillable = ['name', 'category'];
}

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

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

class Frameworks extends Model
{
    // 登録を許可しないカラム
    protected $guarded = ['admin'];
}

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

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

protected $guarded = [];

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

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

$data = $this->frameworks
     ->create([
         'category' => 'Java',
         'name' => 'JSF'
     ]);

firstOrCreate

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

$data = $this->frameworks
     ->firstOrCreate(
         ['name' => 'Laravel'],
         ['category' => 'PHP']
     );

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

ちなみに該当するレコードが存在する場合はインサートは行われず、そのレコードが返されます。

firstOrNew

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

$data = $this->frameworks
     ->firstOrNew(
         ['name' => 'Symfony'],
         ['category' => 'PHP']
     );

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

$data = $this->frameworks
         ->firstOrNew(
             ['name' => 'Ember.js'],
             ['category' => 'JS']
         );

$data->save();

updateOrCreate

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

$this->frameworks
     ->updateOrCreate(
         ['name' => 'React', 'category' => 'JS'],
         ['category' => 'Javascript']
     );

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

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

delete()

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

$model = $this->frameworks->find(28);
$model->delete();

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

と言っておいて難ですが、メソッドチェーンで一撃削除も出来ます。

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

destroy()

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

// １件の削除
$this->frameworks->destroy(24);

// 複数件まとめて削除
$this->frameworks->destroy([25, 26, 27]);

// 複数件まとめて削除
$this->frameworks->destroy(17, 18, 19);

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

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

グローバルスコープ

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

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

laravel
├─ app
│   ├─ Scopes
│   │   └─ CategoryScope.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
{
    /**
     * Eloquentクエリビルダへ適用するスコープ
     *
     * @param  \Illuminate\Database\Eloquent\Builder  $builder
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('category', 'PHP');
    }
}

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

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

laravel/app/Models/Frameworks.php

<?php

namespace App\Models;

use App\Scopes\CategoryScope;
use Illuminate\Database\Eloquent\Model;

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

        static::addGlobalScope(new CategoryScope);
    }
}

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

$this->frameworks->all();
    =>  select * from `frameworks` where `category` = 'PHP';

ある状況で一時的にあるグローバルスコープを外したい場合があるかもしれません。その場合はwithoutGlobalScope()メソッドを使います。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Frameworks;
use App\Scopes\CategoryScope;

class SampleController extends Controller
{
    protected $frameworks;

    public function __construct()
    {
        $this->frameworks = new Frameworks();
    }

    public function index()
    {
        // 指定グローバルスコープをスキップ
        $data = $this->frameworks->withoutGlobalScope(CategoryScope::class)->get();
    }
}

複数、もしくは全てのグルーバルスコープを解除したい場合は以下のように定義します。

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

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

ローカルスコープ

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

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

laravel/app/Models/Frameworks.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Frameworks extends Model
{
    // 登録を許可するカラム
    protected $fillable = ['name', 'category'];

    /**
     * カテゴリーがPHPのものだけに限定するクエリスコープ
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeCategoryPhp($query)
    {
        return $query->where('category', 'PHP');
    }

    /**
     * カテゴリーがPythonのものだけに限定するクエリスコープ
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeCategoryPython($query)
    {
        return $query->where('category', 'Python');
    }
}

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

これで定義は完了です。コントローラから使用してみます。

public function index()
{
    // CategoryPhpスコープを適用する
    $data = $this->frameworks->CategoryPhp()->get();

    // CategoryPhpスコープとCategoryPythonスコープの両方を適用する
    $data = $this->frameworks->CategoryPhp()->CategoryPython()->get();
}

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

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

/**
 * １つのカテゴリーに限定するクエリスコープ
 *
 * @param \Illuminate\Database\Eloquent\Builder $query
 * @return \Illuminate\Database\Eloquent\Builder
 */
public function scopeCategory($query, $type)
{
    return $query->where('category', $type);
}

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

// カテゴリがPHPのものに限定する
$data = $this->frameworks->Category('PHP')->get();

オブザーバクラス

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

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

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

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

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

laravel/app/Observers/FrameworksObserver.php

<?php

namespace App\Observers;

use App\Models\Frameworks;
use Log;
use App\Events\AccessDetection;

/**
 * Frameworksモデルのオブザーバクラス
 * Class FrameworksObserver
 * @package App\Observers
 */
class FrameworksObserver
{
    /**
     * モデル取得イベントのリッスン
     *
     * @param  \App\Models\Frameworks  $frameworks
     * @return void
     */
    public function retrieved(Frameworks $frameworks)
    {
        // ログの書き込み
        Log::debug($frameworks->name);
        // イベント発火
        event(new AccessDetection(str_random(100)));
    }

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

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

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

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