Laravel - Eloquent ORM - Collections (官方文件原子化翻譯筆記)

# Introduction

學習一個框架, Ray 的想法是, 在深入理解底層實作的原理之前, 應該先知道這個框架的 使用方法; 先學習怎麼使用這個前人造的輪子, 再學習怎麼樣造一個輪子。
所以本篇文章重點在於細讀官方文件, 並將內容理解後以 Q&A 的方式記錄下來, 加速學習以及查詢。

# Available Methods

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users->contains(1);
  
  $users->contains(User::find(1));

• Answer:
  判斷 Eloquent collection $users 是否含有 primary key 為 1 的 model, 或直接帶入 model

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use App\Models\User;
  
  $users = $users->diff(User::whereIn('id', [1, 2, 3])->get());

• Answer:
  取得 $users eloquent collection 中, 非 User::whereIn('id', [1,2,3])->get() 的 model

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = $users->except([1, 2, 3]);

• Answer:
  取得 $users eloquent model 中, primary key 非為 [1,2,3] 的 models

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = User::all();
  
  $user = $users->find(1);

• Answer:
  可帶入 primary key, 或 array of primary key, 或 model

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = $users->fresh();
  
  $users = $users->fresh('comments');

• Answer:
  從資料庫重新取得 $users eloquent collection 中的所有 model, 若是帶入 relation, 則該 relation 會被 eager loaded

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use App\Models\User;
  
  $users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());

• Answer:
  取得 $users eloquent collection 中, 與 intersect() arg 重疊的 models

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users->load(['comments', 'posts']);
  
  $users->load('comments.author');

• Answer:
  eager load $users eloquent collection 中所有 model 的指定 relations

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users->loadMissing(['comments', 'posts']);
  
  $users->loadMissing('comments.author');

• Answer:
  如果 $users collection 中的 model 還沒有 eager load 指定的 relation, eager load it

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users->modelKeys();
  
  // [1, 2, 3, 4, 5]

• Answer:
  取得 $user eloquent collection 中 model 的 primary key

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = $users->makeVisible(['address', 'phone_number']);

• Answer:
  將 $users eloquent collection 中的 model, 設為 hidden 的 attribute 改為 visible

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = $users->makeHidden(['address', 'phone_number']);

• Answer:
  將 $users eloquent collection 中的 model 設為 visible 的 attribute 改為 hidden

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = $users->only([1, 2, 3]);

• Answer:
  只取得 given primary key 的 model

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use App\Models\User;
  
  $users = User::where('status', 'VIP')->get();
  
  $users->toQuery()->update([
      'status' => 'Administrator',
  ]);

• Answer:
  將 $user eloquent collection 轉為含有 whereIn 現有 model primary key constraint 的 query builder

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = $users->unique();

• Answer:
  移除 $users eloquent collection 中, 有相同 primary key 的 model

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Models;
  
  use App\Support\UserCollection;
  use Illuminate\Database\Eloquent\Model;
  
  class User extends Model
  {
      public function newCollection(array $models = [])
      {
          return new UserCollection($models);
      }
  }

• Answer:
  如果想要自訂特定 model 的 collection, 可使用 newCollection, 如果想要取得所有 model 的 collection, 可定義在 base model, 如 example, 可定義一個 UserCollection class, 在 newCollection method 中 return 該 class, 之後便可在 UserCollection class 中自定義 collection method