README

Mongodb 和 Laravel 框架 5 的 Eloquent ORM 集成使用的自验证智能模型。

基于 Colby Rabideau 的 Laravel 3 意识包。

安装

将 martingg88/laravel-ardent-mongod 添加到 composer.json 中的需求（查看最新的稳定版本！）

{
    "require": {
        "martingg88/laravel-ardent-mongodb": "3.*"
    }
}

使用 composer update 更新您的包，或使用 composer install 安装。

您还可以使用 composer require martingg88/laravel-ardent-mongod 添加包，并随后指定您想要的版本（目前，dev-master 是您最好的选择）。

（自 1.1 版本以来）Laravel 之外的使用

如果您想将 Ardent 作为独立的 ORM 包使用，请在项目的启动文件中使用以下配置（根据您的数据库更改属性）

\LaravelArdent\Ardent\Ardent::configureAsExternal(array(
  'driver'    => 'mysql',
  'host'      => 'localhost',
  'port'      => 3306,
  'database'  => 'my_system',
  'username'  => 'myself',
  'password'  => 'h4ckr',
  'charset'   => 'utf8',
  'collation' => 'utf8_unicode_ci'
), 'en'); //English is the default messages language, may be left empty

简介

您在构建的应用程序中是否经常需要重新创建相同的样板代码？您是否觉得典型的表单处理代码看起来非常熟悉？

Route::post('register', function() {
        $rules = array(
            'name'                  => 'required|between:3,80|alpha_dash',
            'email'                 => 'required|between:5,64|email|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::get('password'))
                ));

            return Redirect::to('/')->with('message', 'Thanks for registering!');
        } else {
            return Redirect::to('/')->withErrors($validator->getMessages());
        }
    }
);

自己实现通常会导致大量的重复样板代码。作为额外的奖励，您的控制器（或路由处理器）会提前变得臃肿，您的代码变得混乱、丑陋且难以理解。

如果有人为您做所有繁重的工作呢？如果，您只需要输入这些几行代码，而不是重复上面的混乱，那会怎么样？...

Route::post('register', function() {
        $user = new User;
        if ($user->save()) {
            return Redirect::to('/')->with('message', 'Thanks for registering!');
        } else {
            return Redirect::to('/')->withErrors($user->errors());
        }
    }
);

进入 Ardent！

Ardent - 魔法尘埃驱动的、腕部友好的、一站式解决方案，解决您所有枯燥的输入清理样板代码！

开个玩笑，输入验证功能可以快速变得乏味并难以编写和维护。Ardent 通过提供用于自动化许多重复任务的辅助器来处理这些复杂性。

虽然 Ardent 非常适合输入验证，但它还将帮助您显着减少您的 Eloquent 数据模型代码。如果您发现自己多次在多个单独的应用程序中重复编写非常相似的课程，Ardent 特别有用。

例如，用户注册或博客文章提交是常见的编码需求，您可能希望在一个应用程序中实现它，然后在其他应用程序中再次使用它。使用 Ardent，您可以一次编写您的 自我感知、智能 模型，然后在其他项目中重用它（无需或仅进行少量修改）。一旦您习惯了这种做事方式，您就会真诚地想知道在没有 Ardent 的情况下您是如何应对的。

不再有重复的大脑损伤了！

入门

Ardent 旨在扩展 Eloquent 基类，而不改变其核心功能。由于 Ardent 本身是 Illuminate\Database\Eloquent\Model 的后代，因此您的所有 Ardent 模型都与 Eloquent 完全兼容，并且可以利用 Laravel 优秀的 OR/M 的全部功能。

要创建一个新的Ardent模型，只需让您的模型类继承自Ardent基类。在下面的示例中，我们将使用完整命名空间类来使示例更简洁，但您被鼓励在所有类中使用use。

use LaravelArdent\Ardent\Ardent;

class User extends Ardent {}

注意：您可以将您的纯Eloquent模型与Ardent后代自由混合。如果一个模型对象不依赖于用户提交的内容，因此不需要验证，您可以将Eloquent模型类保持原样。

Ardent 的简单验证

Ardent模型使用Laravel内置的验证器类。为模型定义验证规则很简单，通常在模型类中以静态变量的形式完成。

class User extends \LaravelArdent\Ardent\Ardent {
  public static $rules = array(
    'name'                  => 'required|between:3,80|alpha_dash',
    'email'                 => 'required|between:5,64|email|unique:users',
    'password'              => 'required|min:6|confirmed',
    'password_confirmation' => 'required|min:6',
  );
}

注意：您还可以使用数组语法为验证规则。希望您不介意旧的Laravel文档链接，但不幸的是，由于5.1的更新，关于管道/数组语法的验证规则清晰参考已经消失了。

Ardent模型在调用Ardent->save()时自动验证自己。

$user           = new User;
$user->name     = 'John doe';
$user->email    = 'john@doe.com';
$user->password = 'test';

$success = $user->save(); // returns false if model is invalid

注意：您也可以在任何时候使用Ardent->validate()方法来验证模型。

检索验证错误

当Ardent模型验证失败时，一个包含验证失败信息的Illuminate\Support\MessageBag对象将附加到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()；因此，如果您传递一个数组，则不会进行覆盖。

自定义验证错误消息

与Laravel Validator一样，Ardent允许您使用相同的语法设置自定义错误消息。

class User extends \LaravelArdent\Ardent\Ardent {
  public static $customMessages = array(
    'required' => 'The :attribute field is required.',
    ...
  );
}

自定义验证规则

您可以通过相同的方式为Ardent创建自定义验证规则。

模型钩子（自2.0以来）

Ardent在Eloquent模型事件上提供了一些语法糖：传统的模型钩子。它们是将额外操作连接到模型生命周期的不同时刻的简单方法。它们可以用于在删除条目之前执行额外清理工作，在验证后执行自动修复或更新更新后的相关模型。

所有返回false的before钩子（特别是布尔值，而不是简单的“假”值）将停止操作。因此，例如，如果您想在beforeSave方法中停止保存，只需返回false，则保存将不会发生——显然也不会调用afterSave。

以下是所有可用钩子的完整列表

before/afterCreate()
before/afterSave()
before/afterUpdate()
before/afterDelete()
before/afterValidate() - 当返回 false 时将终止验证，因此验证失败也会导致 save() 操作失败。

例如，您可以使用 beforeSave 来对用户的密码进行散列（实际上，使用自动散列会更好！)

class User extends \LaravelArdent\Ardent\Ardent {
  public function beforeSave() {
    // if there's a new password, hash it
    if($this->isDirty('password')) {
      $this->password = Hash::make($this->password);
    }
    
    return true;
    //or don't return nothing, since only a boolean false will halt the operation
  }
}

从 1.0 版本开始，增加了 beforeSave 和 afterSave

beforeSave 和 afterSave 可以在运行时包含。只需将带有模型作为参数的闭包传递给 save()（或 forceSave()）方法。

$user->save(array(), array(), array(),
  function ($model) { // closure for beforeSave
    echo "saving the model object...";
    return true;
  },
  function ($model) { // closure for afterSave
    echo "done!";
  }
);

注意：闭包应有一个参数，因为它将传递正在保存的模型的引用。

更清晰的关联定义（自 2.0 开始）

您是否曾经编写了一个包含许多关系的 Eloquent 模型，只是注意到您的类是多么的杂乱，所有的单行代码几乎与方法名本身的内容相同？

在 Ardent 中，您可以使用数组以干净的方式定义您的关联及其信息，它们将像您在方法中定义它们一样工作。以下是一个示例

class User extends \LaravelArdent\Ardent\Ardent {
  public static $relationsData = array(
    'address' => array(self::HAS_ONE, 'Address'),
    'orders'  => array(self::HAS_MANY, 'Order'),
    'groups'  => array(self::BELONGS_TO_MANY, 'Group', 'table' => '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 实体

Ardent 能够自动从表单输入提交中填充您的实体模型类！

让我们看看它的实际应用。考虑以下代码片段

$user           = new User;
$user->name     = Input::get('name');
$user->email    = Input::get('email');
$user->password = Hash::make(Input::get('password'));
$user->save();

让我们调用 Ardent 的魔力并重写前面的片段

$user = new User;
$user->save();

就是这样！我们只是删除了无聊的部分。

信或不信，上面的代码实际上执行的任务与它的旧版本几乎相同。Ardent 使用用户提交的表单数据填充模型对象的属性。不再需要费力地找出您忘记填充的哪个 Eloquent 属性。让 Ardent 处理无聊的事情，而您则专注于有趣的事情！
它遵循相同的批量赋值规则，具体取决于 $fillable/$guarded 属性。

要启用自动填充功能，只需将模型类中的 $autoHydrateEntityFromInput 实例变量设置为 true。但是，为了防止填充已存在的属性，如果您想更新场景中也进行自动填充，则应使用 $forceEntityHydrationFromInput

class User extends \LaravelArdent\Ardent\Ardent {
  public $autoHydrateEntityFromInput = true;    // hydrates on new entries' validation
  public $forceEntityHydrationFromInput = true; // hydrates whenever validation is called
}

自动清除冗余表单数据

热情模型可以自动清除冗余输入数据（例如密码确认、隐藏的CSRF _token或自定义HTTP _method字段）——这样就不会将额外的数据保存到数据库中。Ardent将使用确认字段来验证表单输入，然后在将模型实例保存到数据库之前谨慎地丢弃这些属性！

要启用此功能，只需在您的模型类中将实例变量$autoPurgeRedundantAttributes设置为true

class User extends \LaravelArdent\Ardent\Ardent {
  public $autoPurgeRedundantAttributes = true;
}

您还可以清除额外的字段。属性Ardent::$purgeFilters是一个闭包数组，您可以添加自定义规则。这些闭包接收属性键作为参数，并且对于应被清除的属性应返回false。例如

function __construct($attributes = array()) {
  parent::__construct($attributes);

  $this->purgeFilters[] = function($key) {
    $purge = array('tempData', 'myAttribute');
    return ! in_array($key, $purge);
  };
}

自动转换安全文本属性

假设您的模型类中有一个名为password的属性，但不想将其明文版本存储在数据库中。务实的方法是存储原始内容的哈希。别担心，Ardent能够自动为您转换任意数量的安全字段！

为此，将属性名添加到您的模型类中的静态数组变量Ardent::$passwordAttributes中，并将实例变量$autoHashPasswordAttributes设置为true

class User extends \LaravelArdent\Ardent\Ardent {
  public static $passwordAttributes  = array('password');
  public $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文档中

    'email' => 'unique:users,email,10'

过去，程序员必须手动管理ID的传递和规则集的更改，以包括ID。但在Ardent中不是这样。只需设置带有unique的规则，调用函数updateUniques，Ardent就会处理剩下的工作。

示例

在您的扩展模型中定义您的规则

  public static $rules = array(
     'email' => 'required|email|unique',
     'password' => 'required|between:4,20|confirmed',
     'password_confirmation' => 'between:4,20',
  );

在您的控制器中，当您需要更新时，只需调用

$model->updateUniques();

如有必要，您可以运行时将规则传递给updateUniques，否则它将使用模型提供的静态规则。

注意，在上面的规则示例中，我们没有告诉验证器使用哪个表或字段，如Laravel文档中所述（即unique:users,email,10）。Ardent足够聪明，能够自己找出这些信息。

malith124 / laravel-ardent-mongodb

维护者

详细信息