Eloquent ORM快速入門 · laravel 5.4

<article><h1>Eloquent: 入門</h1><ul><li><a href="#introduction">簡介</a></li><li><a href="#defining-models">定義模型</a><ul><li><a href="#eloquent-model-conventions">Eloquent 模型約定</a></li></ul></li><li><a href="#retrieving-models">取回多個模型</a><ul><li><a href="#collections">集合</a></li><li><a href="#chunking-results">分塊結果</a></li></ul></li><li><a href="#retrieving-single-models">取回單個模型或集合</a><ul><li><a href="#retrieving-aggregates">取回集合</a></li></ul></li><li><a href="#inserting-and-updating-models">添加和更新模型</a><ul><li><a href="#inserts">基本添加</a></li><li><a href="#updates">基本更新</a></li><li><a href="#mass-assignment">批量賦值</a></li><li><a href="#other-creation-methods">其他創建方法</a></li></ul></li><li><a href="#deleting-models">刪除模型</a><ul><li><a href="#soft-deleting">軟刪除</a></li><li><a href="#querying-soft-deleted-models">查詢被軟刪除的模型</a></li></ul></li><li><a href="#query-scopes">查詢作用域</a><ul><li><a href="#global-scopes">全局作用域</a></li><li><a href="#local-scopes">本地作用域</a></li></ul></li><li><a href="#events">事件</a><ul><li><a href="#observers">觀察器</a></li></ul></li></ul><a name="introduction"></a><h2><a href="#introduction">簡介</a></h2>Laravel 的 Eloquent ORM 提供了漂亮、簡潔的 ActiveRecord 實現來和數據庫進行交互。每個數據庫表都有一個對應的「模型」可用來跟數據表進行交互。你可以通過模型查詢數據表內的數據，以及將記錄添加到數據表中。在開始之前，請確認你已在 <code class=" language-php">config/database.php</code> 文件中設置好了數據庫連接。更多數據庫的設置信息請查看 <a href="/docs/5.4/database#configuration">數據庫設置</a> 文檔。<a name="defining-models"></a><h2><a href="#defining-models">定義模型</a></h2>開始之前，讓我們先來創建一個 Eloquent 模型。模型通常放在 <code class=" language-php">app</code> 目錄中，不過你可以將他們隨意放在任何可通過 <code class=" language-php">composer.json</code> 自動加載的地方。所有的 Eloquent 模型都繼承自 <code class=" language-php">Illuminate\Database\Eloquent\Model</code> 類。創建模型實例的最簡單方法是使用 <code class=" language-php">make:model</code> <a href="/docs/5.4/artisan">Artisan 命令</a>：<pre class=" language-php"><code class=" language-php">php artisan make:model User</code></pre>當你生成一個模型時想要順便生成一個 <a href="/docs/5.4/migrations">數據庫遷移</a>，可以使用 <code class=" language-php">--migration</code> 或 <code class=" language-php">-m</code> 選項：<pre class=" language-php"><code class=" language-php">php artisan make:model User --migration php artisan make:model User -m</code></pre><a name="eloquent-model-conventions"></a><h3>Eloquent 模型約定</h3>現在，讓我們來看一個 <code class=" language-php">Flight</code> 模型類的例子，我們將會用它從 <code class=" language-php">flights</code> 數據表中取回與保存信息：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { // }</code></pre><h4>數據表名稱</h4>請注意，我們并沒有告訴 Eloquent <code class=" language-php">Flight</code> 模型該使用哪一個數據表。除非數據表明確地指定了其它名稱，否則將使用類的「蛇形名稱」、復數形式名稱來作為數據表的名稱。因此在此例子中，Eloquent 將會假設 <code class=" language-php">Flight</code> 模型被存儲記錄在 <code class=" language-php">flights</code> 數據表中。你可以在模型上定義一個 <code class=" language-php">table</code> 屬性，用來指定自定義的數據表名稱：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 與模型關聯的數據表 * * @var string */ protected $table = 'my_flights'; }</code></pre><h4>主鍵</h4>Eloquent 也會假設每個數據表都有一個叫做 <code class=" language-php">id</code> 的主鍵字段。你也可以定義一個 <code class=" language-php">$primaryKey</code> 屬性來重寫這個約定。此外，Eloquent 假定主鍵是一個遞增的整數值，這意味著在默認情況下主鍵將自動的被強制轉換為 <code class=" language-php">int</code>。如果你想使用非遞增或者非數字的主鍵，你必須在你的模型 public <code class=" language-php">$incrementing</code> 屬性設置為<code class=" language-php">false</code>。<h4>時間戳</h4>默認情況下，Eloquent 會認為在你的數據庫表有 <code class=" language-php">created_at</code> 和 <code class=" language-php">updated_at</code> 字段。如果你不希望讓 Eloquent 來自動維護這兩個字段，可在模型內將 <code class=" language-php">$timestamps</code> 屬性設置為 <code class=" language-php">false</code>：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 該模型是否被自動維護時間戳 * * @var bool */ public $timestamps = false; }</code></pre>如果你需要自定義自己的時間戳格式，可在模型內設置 <code class=" language-php">$dateFormat</code> 屬性。這個屬性決定了日期應如何在數據庫中存儲，以及當模型被序列化成數組或 JSON 格式：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 模型的日期字段保存格式。 * * @var string */ protected $dateFormat = 'U'; }</code></pre><h4>數據庫連接</h4>默認情況下，所有的 Eloquent 模型會使用應用程序中默認的數據庫連接設置。如果你想為模型指定不同的連接，可以使用 <code class=" language-php">$connection</code> 屬性：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 此模型的連接名稱。 * * @var string */ protected $connection = 'connection-name'; }</code></pre><a name="retrieving-models"></a><h2><a href="#retrieving-models">取回多個模型</a></h2>一旦你創建并 <a href="/docs/5.4/schema">關聯了一個模型到數據表</a> 上，那么你就可以從數據庫中獲取數據。可把每個 Eloquent 模型想像成強大的 <a href="/docs/5.4/queries">查詢構造器</a>，它讓你可以流暢地查詢與模型關聯的數據表。例如：<pre class=" language-php"><code class=" language-php"><?php use App\Flight; $flights = App\Flight::all(); foreach ($flights as $flight) { echo $flight->name; }</code></pre><h4>增加額外的限制</h4>Eloquent 的 <code class=" language-php">all</code> 方法會返回在模型數據表中的所有結果。由于每個 Eloquent 模型都可以當作一個 <a href="/docs/5.4/queries">查詢構造器</a>，所以你可以在查詢中增加規則，然后使用 <code class=" language-php">get</code> 方法來獲取結果：<pre class=" language-php"><code class=" language-php">$flights = App\Flight::where('active', 1) ->orderBy('name', 'desc') ->take(10) ->get();</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 由于 Eloquent 模型是查詢構造器，因此你應當去閱讀所有 <a href="/docs/5.4/queries">查詢構造器</a> 中可用的方法。你可在 Eloquent 查詢中使用這其中的任何方法。</blockquote><a name="collections"></a><h3>集合</h3>類似 <code class=" language-php">all</code> 以及 <code class=" language-php">get</code> 之類的可以取回多個結果的 Eloquent 方法，將會返回一個 <code class=" language-php">Illuminate\Database\Eloquent\Collection</code> 實例。<code class=" language-php">Collection</code> 類提供 <a href="/docs/5.4/eloquent-collections#available-methods">多種輔助函數</a> 來處理你的 Eloquent 結果。<pre class=" language-php"><code class=" language-php">$flights = $flights->reject(function ($flight) { return $flight->cancelled; });</code></pre>當然，你也可以簡單地像數組一樣來遍歷集合：<pre class=" language-php"><code class=" language-php">foreach ($flights as $flight) { echo $flight->name; }</code></pre><a name="chunking-results"></a><h3>分塊結果</h3>如果你需要處理數以千計的 Eloquent 查找結果，則可以使用 <code class=" language-php">chunk</code> 命令。<code class=" language-php">chunk</code> 方法將會獲取一個 Eloquent 模型的「分塊」，并將它們送到指定的 <code class=" language-php">閉包 (Closure)</code> 中進行處理。當你在處理大量結果時，使用 <code class=" language-php">chunk</code> 方法可節省內存：<pre class=" language-php"><code class=" language-php">Flight::chunk(200, function ($flights) { foreach ($flights as $flight) { // } });</code></pre>傳遞到方法的第一個參數表示每次「分塊」時你希望接收的數據數量。閉包則作為第二個參數傳遞，它將會在每次從數據取出分塊時被調用。<h4>使用游標</h4><code class=" language-php">cursor</code> 允許你使用游標來遍歷數據庫數據，一次只執行單個查詢。在處理大數據量請求時 <code class=" language-php">cursor</code> 方法可以大幅度減少內存的使用：<pre class=" language-php"><code class=" language-php">foreach (Flight::where('foo', 'bar')->cursor() as $flight) { // }</code></pre><a name="retrieving-single-models"></a><h2><a href="#retrieving-single-models">取回單個模型／集合</a></h2>當然，除了從指定的數據表取回所有記錄，你也可以通過 <code class=" language-php">find</code> 和 <code class=" language-php">first</code> 方法來取回單條記錄。但這些方法返回的是單個模型的實例，而不是返回模型的集合：<pre class=" language-php"><code class=" language-php">// 通過主鍵取回一個模型... $flight = App\Flight::find(1); // 取回符合查詢限制的第一個模型 ... $flight = App\Flight::where('active', 1)->first();</code></pre>你也可以用主鍵的集合為參數調用<code class=" language-php">find</code>方法，它將返回符合條件的集合：<pre class=" language-php"><code class=" language-php">$flights = App\Flight::find([1, 2, 3]);</code></pre><h4>「未找到」異常</h4>有時候你可能希望在找不到模型時拋出一個異常，這在路由或是控制器內特別有用。<code class=" language-php">findOrFail</code> 以及 <code class=" language-php">firstOrFail</code> 方法會取回查詢的第一個結果。如果沒有找到相應結果，則會拋出一個 <code class=" language-php">Illuminate\Database\Eloquent\ModelNotFoundException</code>：<pre class=" language-php"><code class=" language-php">$model = App\Flight::findOrFail(1); $model = App\Flight::where('legs', '>', 100)->firstOrFail();</code></pre>如果該異常沒有被捕獲，則會自動返回 HTTP <code class=" language-php">404</code> 響應給用戶，因此當使用這些方法時，你沒有必要明確的編寫檢查來返回 <code class=" language-php">404</code> 響應：<pre class=" language-php"><code class=" language-php">Route::get('/api/flights/{id}', function ($id) { return App\Flight::findOrFail($id); });</code></pre><a name="retrieving-aggregates"></a><h3>取回集合</h3>當然，你也可以使用 <code class=" language-php">count</code>、<code class=" language-php">sum</code>、<code class=" language-php">max</code>，和其它 <a href="/docs/5.4/queries">查詢構造器</a> 提供的 <a href="/docs/5.4/queries#aggregates">聚合函數</a>。這些方法會返回適當的標量值，而不是一個完整的模型實例：<pre class=" language-php"><code class=" language-php">$count = App\Flight::where('active', 1)->count(); $max = App\Flight::where('active', 1)->max('price');</code></pre><a name="inserting-and-updating-models"></a><h2><a href="#inserting-and-updating-models">添加和更新模型</a></h2><a name="inserts"></a><h3>基本添加</h3>要在數據庫中創建一條新記錄，只需創建一個新模型實例，并在模型上設置屬性和調用 <code class=" language-php">save</code> 方法即可：<pre class=" language-php"><code class=" language-php"><?php namespace App\Http\Controllers; use App\Flight; use Illuminate\Http\Request; use App\Http\Controllers\Controller; class FlightController extends Controller { /** * 創建一個新的航班實例。 * * @param Request $request * @return Response */ public function store(Request $request) { // 驗證請求... $flight = new Flight; $flight->name = $request->name; $flight->save(); } }</code></pre>在這個例子中，我們把來自 HTTP 請求中的 <code class=" language-php">name</code> 參數簡單地指定給 <code class=" language-php">App\Flight</code> 模型實例的 <code class=" language-php">name</code> 屬性。當我們調用 <code class=" language-php">save</code> 方法，就會添加一條記錄到數據庫中。當 <code class=" language-php">save</code> 方法被調用時，<code class=" language-php">created_at</code> 以及 <code class=" language-php">updated_at</code> 時間戳將會被自動設置，因此我們不需要去手動設置它們。<a name="updates"></a><h3>基本更新</h3><code class=" language-php">save</code> 方法也可以用于更新數據庫中已經存在的模型。要更新模型，則須先取回模型，再設置任何你希望更新的屬性，接著調用 <code class=" language-php">save</code> 方法。同樣的，<code class=" language-php">updated_at</code> 時間戳將會被自動更新，所以我們不需要手動設置它的值：<pre class=" language-php"><code class=" language-php">$flight = App\Flight::find(1); $flight->name = 'New Flight Name'; $flight->save();</code></pre><h4>批量更新</h4>也可以針對符合指定查詢的任意數量模型進行更新。在這個例子中，所有 <code class=" language-php">active</code> 并且 <code class=" language-php">destination</code> 為 <code class=" language-php">San Diego</code> 的航班，都將會被標識為延遲：<pre class=" language-php"><code class=" language-php">App\Flight::where('active', 1) ->where('destination', 'San Diego') ->update(['delayed' => 1]);</code></pre><code class=" language-php">update</code> 方法會期望收到一個含有字段與值對應的數組，而這些字段的內容將會被更新。<blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 當通過“Eloquent”批量更新時，<code class=" language-php">saved</code>和<code class=" language-php">updated</code>模型事件將不會被更新后的模型代替。這是因為批量更新時，模型從來沒有被取回。</blockquote><a name="mass-assignment"></a><h3>批量賦值</h3>你也可以使用 <code class=" language-php">create</code> 方法通過一行代碼來保存一個新模型。被插入數據庫的模型實例將會返回給你。不過，在這樣做之前，你需要先在你的模型上定義一個 <code class=" language-php">fillable</code> 或 <code class=" language-php">guarded</code> 屬性，因為所有的 Eloquent 模型都針對批量賦值（Mass-Assignment）做了保護。當用戶通過 HTTP 請求傳入了非預期的參數，并借助這些參數更改了數據庫中你并不打算要更改的字段，這時就會出現批量賦值（Mass-Assignment）漏洞。例如，惡意用戶可能會通過 HTTP 請求發送 <code class=" language-php">is_admin</code> 參數，然后對應到你模型的 <code class=" language-php">create</code> 方法，此操作能讓該用戶把自己升級為一個管理者。所以，在開始之前，你應該定義好哪些模型屬性是可以被批量賦值的。你可以在模型上使用 <code class=" language-php">$fillable</code> 屬性來實現。例如，讓我們讓 <code class=" language-php">Flight</code> 模型的 <code class=" language-php">name</code> 屬性可以被批量賦值：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 可以被批量賦值的屬性。 * * @var array */ protected $fillable = ['name']; }</code></pre>一旦我們已經設置好可以被批量賦值的屬性，便能通過 <code class=" language-php">create</code> 方法來添加一條新記錄到數據庫。<code class=" language-php">create</code> 方法將返回已經被保存的模型實例：<pre class=" language-php"><code class=" language-php">$flight = App\Flight::create(['name' => 'Flight 10']);</code></pre><h4>Guarding Attributes</h4><code class=" language-php">$fillable</code> 作為一個可以被批量賦值的屬性「白名單」。另外你也可以選擇使用 <code class=" language-php">$guarded</code>。<code class=" language-php">$guarded</code> 屬性應該包含一個你不想要被批量賦值的屬性數組。所有不在數組里面的其它屬性都可以被批量賦值。因此，<code class=" language-php">$guarded</code> 的功能更類似一個「黑名單」。使用的時候應該只選擇 <code class=" language-php">$fillable</code> 或 <code class=" language-php">$guarded</code> 中的其中一個。下面這個例子中，除了 <code class=" language-php">price</code> 所有的屬性都可以被批量賦值：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 不可被批量賦值的屬性。 * * @var array */ protected $guarded = ['price']; }</code></pre>如果你想讓所有的屬性都可以被批量賦值，你應該定義 <code class=" language-php">$guarded</code>為空數組。<pre class=" language-php"><code class=" language-php">/** * 不可被批量賦值的屬性。 * * @var array */ protected $guarded = [];</code></pre><a name="other-creation-methods"></a><h3>其它創建的方法</h3>還有兩種其它方法，你可以用來通過屬性批量賦值創建你的模型：<code class=" language-php">firstOrCreate</code> 和 <code class=" language-php">firstOrNew</code>。<code class=" language-php">firstOrCreate</code> 方法將會使用指定的字段／值對，來嘗試尋找數據庫中的記錄。如果在數據庫中找不到模型，則會使用指定的屬性來添加一條記錄。<code class=" language-php">firstOrNew</code> 方法類似 <code class=" language-php">firstOrCreate</code> 方法，它會嘗試使用指定的屬性在數據庫中尋找符合的紀錄。如果模型未被找到，將會返回一個新的模型實例。請注意 <code class=" language-php">firstOrnew</code> 返回的模型還尚未保存到數據庫。你需要通過手動調用 <code class=" language-php">save</code> 方法來保存它：<pre class=" language-php"><code class=" language-php">// 用屬性取回航班，當結果不存在時創建它... $flight = App\Flight::firstOrCreate(['name' => 'Flight 10']); // 用屬性取回航班，當結果不存在時實例化一個新實例... $flight = App\Flight::firstOrNew(['name' => 'Flight 10']);</code></pre><a name="deleting-models"></a><h2><a href="#deleting-models">刪除模型</a></h2>要刪除模型，必須在模型實例上調用 <code class=" language-php">delete</code> 方法：<pre class=" language-php"><code class=" language-php">$flight = App\Flight::find(1); $flight->delete();</code></pre><h4>通過鍵來刪除現有的模型</h4>在上面的例子中，我們在調用 <code class=" language-php">delete</code> 方法之前會先從數據庫中取回模型。不過，如果你已知道了模型中的主鍵，則可以不用取回模型就能直接刪除它。若要直接刪除，請調用 <code class=" language-php">destroy</code> 方法：<pre class=" language-php"><code class=" language-php">App\Flight::destroy(1); App\Flight::destroy([1, 2, 3]); App\Flight::destroy(1, 2, 3);</code></pre><h4>通過查詢來刪除模型</h4>當然，你也可以運行在一組模型刪除查詢。在這個例子中，我們會刪除被標記為不活躍的所有航班。像批量更新那樣，批量刪除不會刪除的任何被刪除的模型的事件：<pre class=" language-php"><code class=" language-php">$deletedRows = App\Flight::where('active', 0)->delete();</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 當使用 Eloquent 批量刪除語句時，<code class=" language-php">deleting</code> 和 <code class=" language-php">deleted</code> 模型事件不會在被刪除模型實例上觸發。因為刪除語句執行時，不會檢索回模型實例。</blockquote><a name="soft-deleting"></a><h3>軟刪除</h3>除了從數據庫中移除實際記錄，Eloquent 也可以「軟刪除」模型。當模型被軟刪除時，它們并不會真的從數據庫中被移除。而是會在模型上設置一個 <code class=" language-php">deleted_at</code> 屬性并將其添加到數據庫。如果模型有一個非空值 <code class=" language-php">deleted_at</code>，代表模型已經被軟刪除了。要在模型上啟動軟刪除，則必須在模型上使用 <code class=" language-php">Illuminate\Database\Eloquent\SoftDeletes</code> trait 并添加 <code class=" language-php">deleted_at</code> 字段到你的 <code class=" language-php">$dates</code> 屬性上：<pre class=" language-php"><code class=" language-php"><?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']; }</code></pre>當然，你也應該添加 <code class=" language-php">deleted_at</code> 字段到數據表中。Laravel <a href="/docs/5.4/migrations">結構生成器</a> 包含了一個用來創建此字段的輔助函數：<pre class=" language-php"><code class=" language-php">Schema::table('flights', function ($table) { $table->softDeletes(); });</code></pre>現在，當你在模型上調用 <code class=" language-php">delete</code> 方法時，<code class=" language-php">deleted_at</code> 字段將會被設置成目前的日期和時間。而且，當查詢有啟用軟刪除的模型時，被軟刪除的模型將會自動從所有查詢結果中排除。要確認指定的模型實例是否已經被軟刪除，可以使用 <code class=" language-php">trashed</code> 方法：<pre class=" language-php"><code class=" language-php">if ($flight->trashed()) { // }</code></pre><a name="querying-soft-deleted-models"></a><h3>查詢被軟刪除的模型</h3><h4>包含被軟刪除的模型</h4>如上所述，被軟刪除的模型將會自動從所有的查詢結果中排除。不過，你可以通過在查詢中調用 <code class=" language-php">withTrashed</code> 方法來強制查詢已被軟刪除的模型：<pre class=" language-php"><code class=" language-php">$flights = App\Flight::withTrashed() ->where('account_id', 1) ->get();</code></pre><code class=" language-php">withTrashed</code> 方法也可以被用在 <a href="/docs/5.4/eloquent-relationships">關聯</a> 查詢：<pre class=" language-php"><code class=" language-php">$flight->history()->withTrashed()->get();</code></pre><h4>只取出軟刪除數據</h4><code class=" language-php">onlyTrashed</code> 會只取出軟刪除數據：<pre class=" language-php"><code class=" language-php">$flights = App\Flight::onlyTrashed() ->where('airline_id', 1) ->get();</code></pre><h4>恢復被軟刪除的模型</h4>有時候你可能希望「取消刪除」一個已被軟刪除的模型。要恢復一個已被軟刪除的模型到有效狀態，則可在模型實例上使用 <code class=" language-php">restore</code> 方法：<pre class=" language-php"><code class=" language-php">$flight->restore();</code></pre>你也可以在查詢上使用 <code class=" language-php">restore</code> 方法來快速地恢復多個模型：<pre class=" language-php"><code class=" language-php">App\Flight::withTrashed() ->where('airline_id', 1) ->restore();</code></pre>與 <code class=" language-php">withTrashed</code> 方法類似，<code class=" language-php">restore</code> 方法也可以被用在 <a href="/docs/5.4/eloquent-relationships">關聯</a> 查詢上:<pre class=" language-php"><code class=" language-php">$flight->history()->restore();</code></pre><h4>永久地刪除模型</h4>有時候你可能需要真正地從數據庫移除模型。要永久地從數據庫移除一個已被軟刪除的模型，則可使用 <code class=" language-php">forceDelete</code> 方法：<pre class=" language-php"><code class=" language-php">// 強制刪除單個模型實例... $flight->forceDelete(); // 強制刪除所有相關模型... $flight->history()->forceDelete();</code></pre><a name="query-scopes"></a><h2><a href="#query-scopes">查詢作用域</a></h2><a name="global-scopes"></a><h3>全局作用域</h3>全局作用域允許我們為給定模型的所有查詢添加條件約束。Laravel 自帶的 <a href="#soft-deleting">軟刪除功能</a> 就使用了全局作用域來從數據庫中拉出所有沒有被刪除的模型。編寫自定義的全局作用域可以提供一種方便的、簡單的方式，來確保給定模型的每個查詢都有特定的條件約束。<h4>編寫全局作用域</h4>自定義全局作用域很簡單，首先定義一個實現 <code class=" language-php">Illuminate\Database\Eloquent\Scope</code> 接口的類，該接口要求你實現一個方法：<code class=" language-php">apply</code>。需要的話可以在 <code class=" language-php">apply</code> 方法中添加 <code class=" language-php">where</code> 條件到查詢：<pre class=" language-php"><code class=" language-php"><?php namespace App\Scopes; use Illuminate\Database\Eloquent\Scope; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Builder; class AgeScope implements Scope { /** * 應用作用域 * * @param \Illuminate\Database\Eloquent\Builder $builder * @param \Illuminate\Database\Eloquent\Model $model * @return void */ public function apply(Builder $builder, Model $model) { return $builder->where('age', '>', 200); } }</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> Laravel 沒有規定你需要把這些類放置于哪個文件夾，你可以自由在 <code class=" language-php">app</code> 文件夾下創建 <code class=" language-php">Scopes</code> 文件夾來存放。</blockquote><h4>應用全局作用域</h4>要將全局作用域分配給模型，需要重寫給定模型的 <code class=" language-php">boot</code> 方法并使用 <code class=" language-php">addGlobalScope</code> 方法：<pre class=" language-php"><code class=" language-php"><?php namespace App; use App\Scopes\AgeScope; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 數據模型的啟動方法 * * @return void */ protected static function boot() { parent::boot(); static::addGlobalScope(new AgeScope); } }</code></pre>添加作用域后，如果使用 <code class=" language-php">User::all()</code> 查詢則會生成如下SQL語句：<pre class=" language-php"><code class=" language-php">select * from `users` where `age` > 200</code></pre><h4>匿名的全局作用域</h4>Eloquent 還允許我們使用閉包定義全局作用域，這在實現簡單作用域的時候特別有用，這樣的話，我們就沒必要定義一個單獨的類了：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Builder; class User extends Model { /** * 數據模型的啟動方法 * * @return void */ protected static function boot() { parent::boot(); static::addGlobalScope('age', function(Builder $builder) { $builder->where('age', '>', 200); }); } }</code></pre>我們還可以通過以下方式，利用 <code class=" language-php">age</code> 標識符來移除全局作用：<pre class=" language-php"><code class=" language-php">User::withoutGlobalScope('age')->get();</code></pre><h4>移除全局作用域</h4>如果想要在給定查詢中移除指定全局作用域，可以使用 <code class=" language-php">withoutGlobalScope</code>：<pre class=" language-php"><code class=" language-php">User::withoutGlobalScope(AgeScope::class)->get();</code></pre>如果你想要移除某幾個或全部全局作用域，可以使用 <code class=" language-php">withoutGlobalScopes</code> 方法：<pre class=" language-php"><code class=" language-php">User::withoutGlobalScopes()->get(); User::withoutGlobalScopes([FirstScope::class, SecondScope::class])->get();</code></pre><a name="local-scopes"></a><h3>本地作用域</h3>本地作用域允許我們定義通用的約束集合以便在應用中復用。例如，你可能經常需要獲取最受歡迎的用戶，要定義這樣的一個作用域，只需簡單在對應 Eloquent 模型方法前加上一個 <code class=" language-php">scope</code> 前綴，作用域總是返回查詢構建器：<pre class=" language-php"><code class=" language-php"><?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); } }</code></pre><h4>利用查詢范圍</h4>一旦定義了范圍，則可以在查詢模型時調用范圍方法。在進行方法調用時不需要加上 <code class=" language-php">scope</code> 前綴。你甚至可以鏈式調用不同的范圍，如：<pre class=" language-php"><code class=" language-php">$users = App\User::popular()->active()->orderBy('created_at')->get();</code></pre><h4>動態范圍</h4>有時候，你可能希望定義一個可接受參數的范圍。這時只需給你的范圍加上額外的參數即可。范圍參數應該被定義在 <code class=" language-php">$query</code> 參數之后：<pre class=" language-php"><code class=" language-php"><?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); } }</code></pre>現在，你可以在范圍調用時傳遞參數：<pre class=" language-php"><code class=" language-php">$users = App\User::ofType('admin')->get();</code></pre><a name="events"></a><h2><a href="#events">事件</a></h2>Eloquent 模型會觸發許多事件，讓你在模型的生命周期的多個時間點進行監控： <code class=" language-php">creating</code>, <code class=" language-php">created</code>, <code class=" language-php">updating</code>, <code class=" language-php">updated</code>, <code class=" language-php">saving</code>, <code class=" language-php">saved</code>, <code class=" language-php">deleting</code>, <code class=" language-php">deleted</code>, <code class=" language-php">restoring</code>, <code class=" language-php">restored</code>.事件讓你每當有特定的模型類在數據庫保存或更新時，執行代碼。當一個新模型被初次保存將會觸發 <code class=" language-php">creating</code> 以及 <code class=" language-php">created</code> 事件。如果一個模型已經存在于數據庫且調用了 <code class=" language-php">save</code> 方法，將會觸發 <code class=" language-php">updating</code> 和 <code class=" language-php">updated</code> 事件。在這兩種情況下都會觸發 <code class=" language-php">saving</code> 和 <code class=" language-php">saved</code> 事件。開始前，在你的 Eloquent 模型上定義一個 <code class=" language-php">$events</code> 屬性，將 Eloquent 模型的生命周期的多個點映射到你的 <a href="/docs/5.4/providers">服務提供者</a> 。<pre class=" language-php"><code class=" language-php"><?php namespace App; use App\Events\UserSaved; use App\Events\UserDeleted; use Illuminate\Notifications\Notifiable; use Illuminate\Foundation\Auth\User as Authenticatable; class User extends Authenticatable { use Notifiable; /** * 模型的時間映射。 * * @var array */ protected $events = [ 'saved' => UserSaved::class, 'deleted' => UserDeleted::class, ]; }</code></pre><a name="observers"></a><h3>觀察者</h3>如果你在一個給定的模型中監聽許多事件，您可以使用觀察者將所有監聽器變成一個類。觀察者類里的方法名應該反映Eloquent想監聽的事件。每種方法接收 model 作為其唯一的參數。 Laravel不包括觀察者默認目錄，所以你可以創建任何你喜歡你的目錄來存放：<pre class=" language-php"><code class=" language-php"><?php namespace App\Observers; use App\User; class UserObserver { /** * 監聽用戶創建的事件。 * * @param User $user * @return void */ public function created(User $user) { // } /** * 監聽用戶刪除事件。 * * @param User $user * @return void */ public function deleting(User $user) { // } }</code></pre>要注冊一個觀察者，需要用模型中的<code class=" language-php">observe</code>方法去觀察。你可以在你的服務提供商之一的<code class=" language-php">boot</code>方法中注冊觀察者。在這個例子中，我們將在<code class=" language-php">AppServiceProvider</code>注冊觀察者：<pre class=" language-php"><code class=" language-php"><?php namespace App\Providers; use App\User; use App\Observers\UserObserver; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { /** * 運行所有應用. * * @return void */ public function boot() { User::observe(UserObserver::class); } /** * 注冊服務提供. * * @return void */ public function register() { // } }</code></pre><h2>譯者署名</h2><table><thead><tr><th>用戶名</th><th>頭像</th><th>職能</th><th>簽名</th></tr></thead><tbody><tr><td><a href="https://github.com/dongli0">@LXY</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/5832_1473813539.jpeg?imageView2/1/w/380/h/380"></td><td>翻譯</td><td>PHP 小學生。</td></tr></tbody></table></article>