ardent

熱心

Laravel Framework 5 的 Eloquent ORM 的自我驗證智慧模型。

基於 Colby Rabideau 的 Laravel 3 Aware 套件。

版權所有 (C) 2013-2015 Max Ehsan 和 Igor Santos

變更日誌

請造訪我們的版本清單。變更日誌是在那裡製作的:)

安裝

新增laravelbook/ardent作為composer.json的要求（請參閱徽章上的最新穩定版本！）：

 {"require": {"laravelbook/ardent": "3.*"}}

使用composer update更新您的軟體包或使用composer install安裝。

您也可以使用composer require laravelbook/ardent新增包，然後指定您想要的版本（目前， dev-master是您最好的選擇）。

在 Laravel 以外使用（自 1.1 起）

如果您想將 Ardent 用作獨立的 ORM 包，我們邀請您在專案的引導/啟動文件中使用以下配置（顯然，根據您的資料庫更改屬性）：

 LaravelArdentArdentArdent::configureAsExternal(array( 'driver' => 'mysql', 'host' => 'localhost', 'port' => 3306, 'database' => 'my_system', 'username' => 'myself', '密碼' => 'h4ckr', '字元集' => 'utf8', '排序規則' => 'utf8_unicode_ci'), 'en'); //預設訊息語言為英語，可以留空

---

文件

• 介紹

• 入門

• 使用 Ardent 輕鬆進行驗證

• 檢索驗證錯誤

• 重寫驗證

• 自訂驗證錯誤訊息

• 自訂驗證規則

• 模型掛鉤

• 更清晰的關係定義

• 自動水合熱心實體

• 自動清除冗餘表單數據

• 自動轉換安全文字屬性

• 具有獨特規則的更新

介紹

您是否經常發現自己在構建的應用程式中重新創建相同的樣板程式碼？您是否覺得這個典型的表單處理程式碼非常熟悉？

路線::post('註冊', function() {$rules = array('名稱' => '必需|之間:3,80|alpha_dash','電子郵件' => '必要|之間:5, 64|電子郵件|unique:users','password' => 'required|min:6|confirmed','password_confirmation' => 'required|min:6');$validator = Validator::make(Input:: all(), $rules);if ($validator->passes()) {
            User::create(array('name' => Input::get('name'),'email' => Input::get('email'),'password' => Hash::make(Input::獲取（'密碼'））
                ));return Redirect::to('/')->with('message', '感謝您註冊！');
        } else {return Redirect::to('/')->withErrors($validator->getMessages());
        }
    }
）；

自己實現這一點通常會導致大量重複的樣板程式碼。作為額外的好處，你的控制器（或路由處理程序）會過早變得臃腫，並且你的程式碼會變得混亂、醜陋且難以理解。

如果別人為你完成所有繁重的工作怎麼辦？如果您不需要重複上面的混亂，而只需要輸入這幾行怎麼辦？ ...

 Route::post('register', function() {$user = new User;if ($user->save()) {return Redirect::to('/')->with('message', '謝謝進行註冊！
        } else {return Redirect::to('/')->withErrors($user->errors());
        }
    }
）；

輸入熱心！

Ardent - 魔法灰塵驅動、手腕友好的一站式解決方案，可解決您所有沉悶的輸入消毒樣板！

撇開雙關語不談，輸入驗證功能的編寫和維護很快就會變得乏味。 Ardent 透過提供協助來自動執行許多重複性任務來解決這些複雜性。

不過，Ardent 不僅適用於輸入驗證，它還可以幫助您大幅減少 Eloquent 資料模型程式碼。如果您發現自己疲倦地在多個單獨的應用程式中一次又一次地編寫非常相似的程式碼，那麼 Ardent 特別有用。

例如，用戶註冊或部落格文章提交是一種常見的編碼要求，您可能希望在一個應用程式中實現並在其他應用程式中再次重複使用。借助 Ardent，您只需編寫一次具有自我意識的智慧模型，然後在其他專案中重複使用它們（無需修改或只需很少的修改）。一旦你習慣了這種做事方式，你就會真誠地想知道如果沒有 Ardent，你是如何應對的。

您不再遭受重複性腦勞損！

入門

Ardent目標是在不改變其核心功能的情況下擴展Eloquent基底類別。由於Ardent本身是IlluminateDatabaseEloquentModel的後代，因此所有Ardent模型都與Eloquent完全相容，並且可以充分利用 Laravels Awesome OR/M 的全部功能。

要建立新的 Ardent 模型，只需使模型類別從Ardent基底類別派生即可。在接下來的範例中，我們將使用完整的命名空間類別來使範例更清晰，但鼓勵您在所有類別中使用use ：

使用 LaravelArdentArdentArdent;class User 擴充 Ardent {}

注意：您可以自由地將普通 Eloquent 模型與 Ardent 後代模型混合在一起。如果模型物件不依賴使用者提交的內容，因此不需要驗證 - 您可以保留 Eloquent 模型類別不變。

使用 Ardent 輕鬆進行驗證

Ardent 模型使用 Laravel 內建的 Validator 類別。為模型定義驗證規則很簡單，通常在模型類別中作為靜態變數完成：

 class User extends LaravelArdentArdentArdent { public static $rules = array('name' => 'required| Between:3,80|alpha_dash','email' => 'required| Between:5,64|email|unique:users' => 'required| Between:5,64|email|unique:users' => ' '密碼' => '必備|分鐘:6|確認','password_confirmation' => '必填|分鐘:6',
  ）；
}

注意：您也可以自由使用陣列語法來驗證規則。我希望您不介意舊的 Laravel 文檔鏈接，但與 Laravel 文檔一樣，不幸的是，自 5.1 以來，驗證規則的管道/數組語法的清晰參考已經消失。

當Ardent->save()被呼叫時，Ardent 模型會自動驗證自身。

 $user = 新使用者;$user->name = 'John doe';$user->email = '[email protected]';$user->password = 'test';$success = $user->save( ）； // 如果模型無效則回傳 false

注意：您也可以隨時使用Ardent->validate()方法驗證模型。

檢索驗證錯誤

當 Ardent 模型驗證失敗時，會將IlluminateSupportMessageBag物件附加到包含驗證失敗訊息的 Ardent 物件。

使用Ardent->errors()方法或Ardent->validationErrors屬性檢索驗證錯誤訊息集合實例。

使用Ardent->errors()->all()檢索所有驗證錯誤。使用Ardent->validationErrors->get('attribute')檢索特定屬性的錯誤。

注意： Ardent 利用 Laravel 的 MessagesBag 對象，該對象具有簡單而優雅的格式化錯誤方法。

重寫驗證

有兩種方法可以覆蓋 Ardent 的驗證：

1. 強制保存

forceSave()驗證模型，但無論是否有驗證錯誤都會儲存。

2. 覆蓋規則和訊息

Ardent->save($rules, $customMessages)和Ardent->validate($rules, $customMessages)都採用兩個參數：

• $rules是與Ardent::$rules形式相同的驗證器規則陣列。

• $customMessages參數也是如此（與Ardent::$customMessages相同）

非空數組將覆寫類別僅為該方法實例指定的規則或自訂錯誤訊息。

注意： $rules和$customMessages的預設值為空array() ；因此，如果您傳遞array()則不會覆蓋任何內容。

自訂驗證錯誤訊息

就像 Laravel 驗證器一樣，Ardent 允許您使用相同的語法設定自訂錯誤訊息。

 class User extends LaravelArdentArdentArdent { public static $customMessages = array('required' => ':attribute 欄位是必需的。',
    ……
  ）；
}

自訂驗證規則

您可以像建立 Laravel 驗證器一樣建立自訂驗證規則。

模型掛鉤（自 2.0 起）

Ardent 為 Eloquent 的模型事件提供了一些語法糖：傳統模型掛鉤。它們是一種將額外操作連接到模型生命中不同時刻的簡單方法。它們可用於在刪除條目之前執行額外的清理工作，在驗證發生後執行自動修復或在更新發生後更新相關模型。

所有before鉤子在傳回false （特別是布林值，而不僅僅是「假」值）時將停止操作。因此，舉例來說，如果您想在beforeSave方法出現問題時停止保存，只需return false ，保存就不會發生 - 顯然afterSave也不會被調用。

以下是可用鉤子的完整清單：

• 創建before / afterCreate()

• afterSave() before /之後

• 更新before / afterUpdate()

• afterDelete() before /之後

• before / afterValidate() - 返回 false 時將停止驗證，從而使save()操作也失敗，因為驗證失敗。

例如，您可以使用beforeSave來雜湊使用者密碼（實際上，使用自動雜湊會是一個更好的主意！）：

 class User extends LaravelArdentArdentArdent { public function beforeSave() {// 如果有新密碼，則對其進行哈希if($this->isDirty('password')) { $this->password = Hash::make($ this->password ）；
    } return true;//或不回傳任何內容，因為只有布林值 false 才會停止操作
  }
}

附加的 beforeSave 和 afterSave（自 1.0 起）

beforeSave和afterSave可以在運行時包含。只需將模型作為參數傳遞給save() （或forceSave() ）方法的閉包即可。

 $user->save(array(), array(), array(), function ($model) { // beforeSaveecho 的閉包「儲存模型物件...」;return true;
  }, function ($model) { // afterSaveecho "done!" 的閉包；
  }
）；

注意：閉包應該有一個參數，因為它將傳遞正在儲存的模型的參考。

更清晰的關係定義（自 2.0 起）

您是否曾經編寫過包含一堆關係的 Eloquent 模型，只是注意到您的類別有多麼混亂，所有那些與方法名稱本身內容幾乎相同的單行話？

在 Ardent 中，您可以使用其資訊在陣列中清晰地定義關係，並且它們的工作方式就像您在方法中定義它們一樣。這是一個例子：

 class User extends LaravelArdentArdentArdent { public static $relationsData = array('address' => array(self::HAS_ONE, 'Address'),'orders' => array(self::HAS_MANY, 'Order'),'groups' => array(self::HAS_MANY, 'Order'),'groups' = > 數組(self::BELONGS_TO_MANY, '組', '表' => 'groups_have_users')
  ）；
}$user = User::find($id);echo "{$user->address->street}, {$user->address->city} - {$user->address->state}";

數組語法如下：

• 第一個索引值：關係名稱，為hasOne 、 hasMany 、 belongsTo 、 belongsToMany 、 morphTo 、 morphOne 、 morphMany之一或相關常數之一（例如Ardent::HAS_MANY或Ardent::MORPH_ONE ）。

• 第二個索引：類別名，具有完整的命名空間。 morphTo關係式是個例外，它不需要額外的參數。

• 命名參數，遵循原始 Eloquent 方法定義的參數：

• foreignKey [可選]，對hasOne 、 hasMany 、 belongsTo和belongsToMany有效

• table 、 otherKey [可選]、 timestamps [布林值，可選] 和pivotKeys [數組，可選]，對belongsToMany有效

• name 、 type和id ，由morphTo 、 morphOne和morphMany使用（最後兩個需要定義name ）

注意：此功能是基於 Yii 1.1 ActiveRecord 上的簡單關係。

自動水合熱心實體

Ardent 能夠自動從表單輸入提交中合併您的實體模型類別！

讓我們看看它的動作。考慮一下這段程式碼：

 $user = 新使用者;$user->name = Input::get('name');$user->email = Input::get('email');$user->password = Hash::make(Input ::get('密碼'));$user->save();

讓我們呼叫 Ardent 的魔力並重寫前面的程式碼片段：

 $user = 新使用者;$user->save();

就是這樣！我們所做的就是刪除那些無聊的東西。

不管你相信與否，上面的程式碼執行的任務基本上與它的舊程式碼（儘管相當冗長）相同。 Ardent 使用使用者提交的表單資料中的屬性填入模型物件。不再費力地試圖找出您忘記填充的 Eloquent 屬性。讓 Ardent 處理無聊的事情，而您可以繼續有趣的事情！
它在內部遵循相同的品質分配規則，取決於$fillable / $guarded屬性。

若要啟用自動水合功能，只需在模型類別中將$autoHydrateEntityFromInput實例變數設為true即可。但是，為了防止填充預先存在的屬性，如果您也希望在更新場景中自動水合，則應該使用$forceEntityHydrationFromInput ：

類別 User 擴充 LaravelArdentArdentArdent { public $autoHydrateEntityFromInput = true;    // 水合新條目的驗證
  公共$forceEntityHydrationFromInput = true; // 每當呼叫驗證時都會水化}

自動清除冗餘表單數據

Ardent 模型可以自動神奇地清除冗餘輸入資料（例如密碼確認、隱藏的 CSRF _token或自訂 HTTP _method欄位），以便額外的資料永遠不會儲存到資料庫中。 Ardent 將使用確認欄位來驗證表單輸入，然後在將模型實例儲存到資料庫之前謹慎地丟棄這些屬性！

要啟用此功能，只需在模型類別中將$autoPurgeRedundantAttributes實例變數設為true ：

類別 User 擴充 LaravelArdentArdentArdent { public $autoPurgeRedundantAttributes = true;
}

您也可以清除其他欄位。屬性Ardent::$purgeFilters是一個閉包數組，您可以向其中新增自訂規則。這些閉包接收屬性鍵作為參數，並且對於應清除的屬性應傳回false 。像這樣：

函式 __construct($attributes = array()) { 父階::__construct($attributes);  $this->purgeFilters[] = function($key) {$purge = array('tempData', 'myAttribute');return ! in_array($key, $purge);
  };
}

自動轉換安全文字屬性

假設您的模型類別中有一個名為password的屬性，但不想在資料庫中儲存純文字版本。務實的做法是儲存原始內容的哈希值。不用擔心，Ardent 完全有能力為您自動變換任意數量的安全欄位！

為此，請將屬性名稱新增至模型類別中的Ardent::$passwordAttributes靜態陣列變數中，並將$autoHashPasswordAttributes實例變數設為true ：

 class User 擴充 LaravelArdentArdentArdent { 公共靜態 $passwordAttributes = array('password');  公共 $autoHashPasswordAttributes = true;
}

Ardent 會自動以安全雜湊校驗和取代純文字密碼屬性並將其儲存到資料庫中。它在內部使用 Laravel Hash::make()方法來產生雜湊。注意：建議使用 Eloquent 的$hidden屬性，這樣如果您正在建立 API 或類似的密碼，即使經過雜湊處理，密碼也不會那麼容易洩露:)

如果您獨立使用 Ardent，則可以使用Ardent::$hasher來驗證欄位值，使用類似User::$hasher->check($given_password, $user->password)的內容。

具有獨特規則的更新

Ardent 可以幫助您進行獨特的更新。根據 Laravel 文檔，當您使用唯一規則更新（並因此驗證）欄位時，您必須傳入要更新的記錄的唯一 ID。如果不傳遞此 ID，驗證將會失敗，因為 Laravel 的驗證器會認為此記錄是重複的。

來自 Laravel 文件：

    '電子郵件' => '唯一：用戶，電子郵件，10'

過去，程式設計師必須手動管理 ID 的傳遞和規則集的變更以在執行時間包含 ID。但熱心卻並非如此。只需使用unique設定規則，呼叫函數updateUniques ，Ardent 將處理剩下的事情。

例子：

在您的擴充模型中定義您的規則

  公共靜態$rules = array( '電子郵件' => '必要|電子郵件|唯一', '密碼' => '必要|之間:4,20|確認', 'password_confirmation' => '之間:4 ,20',
  ）；

在你的控制器中，當你需要更新時，只需調用

$模型->updateUniques();

如果需要，您可以在執行時將規則傳遞給updateUniques ，否則它將使用模型提供的靜態規則。

請注意，在上面的規則範例中，我們沒有告訴驗證器要使用哪個表甚至哪個字段，如 Laravel 文件中所述（即unique:users,email,10 ）。熱心夠聰明，能夠弄清楚這一點。 （感謝github用戶@Sylph）