ardent

متحمس

نماذج ذكية ذاتية التحقق لـ Laravel Framework 5's Eloquent ORM.

استنادًا إلى حزمة Aware الخاصة بـ Laravel 3 من تصميم Colby Rabideau.

حقوق الطبع والنشر (C) 2013-2015 ماكس إحسان وإيجور سانتوس

سجل التغيير

قم بزيارة قائمة الإصدارات لدينا. يتم إجراء التغيير هناك :)

تثبيت

أضف laravelbook/ardent كشرط إلى composer.json (راجع أحدث إصدار ثابت لدينا على الشارات!):

 {"يتطلب": {"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', 'password' => 'h4ckr', 'charset' => 'utf8', 'collation' => 'utf8_unicode_ci')، 'ar')؛ // اللغة الإنجليزية هي لغة الرسائل الافتراضية، ويمكن تركها فارغة

---

التوثيق

• مقدمة

• ابدء

• التحقق من صحة جهد مع المتحمسين

• استرداد أخطاء التحقق من الصحة

• تجاوز التحقق من الصحة

• رسائل خطأ التحقق المخصصة

• قواعد التحقق المخصصة

• السنانير النموذجية

• تعريف أنظف للعلاقات

• ترطيب الكيانات المتحمسة تلقائيا

• إزالة بيانات النموذج الزائدة تلقائيًا

• تحويل سمات النص الآمن تلقائيًا

• تحديثات بقواعد فريدة

مقدمة

كم مرة تجد نفسك تعيد إنشاء نفس الكود المعياري في التطبيقات التي تنشئها؟ هل يبدو رمز معالجة النماذج النموذجي هذا مألوفًا بالنسبة لك؟

 الطريق::post('register', function() {$rules = array('name' => 'required|between:3,80|alpha_dash','email' => 'required|between:5,64|email |unique:users','password' => 'مطلوب|الحد الأدنى:6|مؤكد','password_confirmation' => 'required|min:6');$validator = Validator::make(Input::all(), $rules);if ($validator->passes()) {
            المستخدم::create(array('name' => Input::get('name'),'email' => Input::get('email'),'password' => Hash::make(Input:: الحصول على ("كلمة المرور"))
                ));return إعادة التوجيه::to('/')->with('message', 'شكرًا على التسجيل!');
        } else {return Redirect::to('/')->withErrors($validator->getMessages());
        }
    }
);

غالبًا ما يؤدي تنفيذ هذا بنفسك إلى الكثير من التعليمات البرمجية النمطية المتكررة. كمكافأة إضافية، فإن وحدات التحكم (أو معالجات المسار) تصبح سمينة قبل الأوان، وتصبح التعليمات البرمجية الخاصة بك فوضوية وقبيحة ويصعب فهمها.

ماذا لو قام شخص آخر برفع الأثقال نيابةً عنك؟ ماذا لو، بدلاً من تكرار الفوضى المذكورة أعلاه، كل ما تحتاج إلى كتابته هو هذه الأسطر القليلة؟...

 الطريق::post('register', function() {$user = new User;if ($user->save()) {return Redirect::to('/')->with('message', 'Thanks للتسجيل!');
        } else {return Redirect::to('/')->withErrors($user->errors());
        }
    }
);

أدخل المتحمسين!

Ardent - الحل الشامل الذي يعمل بالغبار السحري والصديق للمعصم لجميع لوحات تعقيم المدخلات الكئيبة الخاصة بك!

بغض النظر عن التورية، يمكن أن تصبح وظيفة التحقق من صحة الإدخال مملة في الكتابة والصيانة. يتعامل Ardent مع هذه التعقيدات من خلال توفير مساعدين لأتمتة العديد من المهام المتكررة.

Ardent ليس فقط رائعًا للتحقق من صحة الإدخال، ولكنه سيساعدك بشكل كبير على تقليل كود نموذج بيانات Eloquent الخاص بك. يعد Ardent مفيدًا بشكل خاص إذا وجدت نفسك تشعر بالضجر أثناء كتابة تعليمات برمجية مشابهة جدًا مرارًا وتكرارًا في تطبيقات فردية متعددة.

على سبيل المثال، يعد تسجيل المستخدم أو إرسال منشور مدونة أحد متطلبات الترميز الشائعة التي قد ترغب في تنفيذها في أحد التطبيقات وإعادة استخدامها مرة أخرى في تطبيقات أخرى. باستخدام Ardent، يمكنك كتابة نماذجك الذكية الواعية بذاتها مرة واحدة فقط، ثم إعادة استخدامها (بدون أي تعديلات أو تعديلات قليلة جدًا) في مشاريع أخرى. بمجرد أن تعتاد على هذه الطريقة في فعل الأشياء، سوف تتساءل بصراحة كيف تعاملت بدون Ardent.

لا مزيد من إصابات إجهاد الدماغ المتكررة بالنسبة لك!

ابدء

يهدف Ardent إلى توسيع فئة Eloquent الأساسية دون تغيير وظائفها الأساسية. نظرًا لأن Ardent نفسها هي سليل IlluminateDatabaseEloquentModel ، فإن جميع نماذج Ardent الخاصة بك متوافقة تمامًا مع Eloquent ويمكنها الاستفادة من القوة الكاملة لـ Laravels الرائع OR/M.

لإنشاء نموذج Ardent جديد، ما عليك سوى جعل فئة النموذج الخاصة بك مشتقة من فئة Ardent الأساسية. في الأمثلة التالية، سنستخدم فئة مساحة الاسم الكاملة لجعل الأمثلة أكثر وضوحًا، ولكن ننصحك بالاستفادة من use في جميع فصولك:

 استخدم LaravelArdentArdentArdent;class User يمتد Ardent {}

ملحوظة: يمكنك المزج بحرية بين نماذج Eloquent ذات اللون الفانيليا العادي وأحفاد Ardent. إذا كان كائن النموذج لا يعتمد على المحتوى المقدم من المستخدم وبالتالي لا يتطلب التحقق من الصحة - فيمكنك ترك فئة نموذج Eloquent كما هي.

التحقق من صحة جهد مع المتحمسين

تستخدم نماذج Ardent فئة Validator المضمنة في Laravel. يعد تحديد قواعد التحقق من صحة النموذج أمرًا بسيطًا ويتم إجراؤه عادةً في فئة النموذج الخاص بك كمتغير ثابت:

 فئة المستخدم يمتد LaravelArdentArdentArdent { public static $rules = array('name' => 'required|between:3,80|alpha_dash','email' => 'required|between:5,64|email|unique:users', 'كلمة المرور' => 'مطلوبة|الحد الأدنى:6|مؤكدة','password_confirmation' => 'مطلوب|الحد الأدنى:6'،
  );
}

ملاحظة : لك الحرية في استخدام بناء جملة المصفوفة لقواعد التحقق من الصحة أيضًا. أتمنى ألا تمانع في رابط مستندات Laravel القديم، ولكن على الرغم من جودة وثائق Laravel، فقد اختفى لسوء الحظ مرجع واضح حول بناء جملة توجيه الإخراج/المصفوفة لقواعد التحقق من الصحة منذ الإصدار 5.1.

تتحقق نماذج Ardent من صحتها تلقائيًا عند استدعاء Ardent->save() .

 $user = مستخدم جديد;$user->name = 'John doe';$user->email = '[email protected]';$user->password = 'test';$success = $user->save( ); // يُرجع خطأ إذا كان النموذج غير صالح

ملاحظة: يمكنك أيضًا التحقق من صحة النموذج في أي وقت باستخدام طريقة Ardent->validate() .

استرداد أخطاء التحقق من الصحة

عندما يفشل نموذج Ardent في التحقق من الصحة، يتم إرفاق كائن IlluminateSupportMessageBag بكائن Ardent الذي يحتوي على رسائل فشل التحقق من الصحة.

قم باسترجاع نسخة مجموعة رسائل أخطاء التحقق باستخدام طريقة Ardent->errors() أو خاصية Ardent->validationErrors .

استرجع جميع أخطاء التحقق باستخدام Ardent->errors()->all() . استرداد الأخطاء لسمة معينة باستخدام Ardent->validationErrors->get('attribute') .

ملاحظة: يعمل Ardent على الاستفادة من كائن MessagesBag الخاص بـ Laravel والذي يتمتع بطريقة بسيطة وأنيقة لأخطاء التنسيق.

تجاوز التحقق من الصحة

هناك طريقتان لتجاوز التحقق من صحة Ardent:

1. الحفظ القسري

يقوم forceSave() بالتحقق من صحة النموذج ولكنه يحفظ بغض النظر عما إذا كانت هناك أخطاء في التحقق أم لا.

2. تجاوز القواعد والرسائل

يأخذ كل من Ardent->save($rules, $customMessages) و Ardent->validate($rules, $customMessages) معلمتين:

• $rules عبارة عن مصفوفة من قواعد Validator بنفس شكل Ardent::$rules .

• وينطبق الشيء نفسه على المعلمة $customMessages (مثل Ardent::$customMessages )

سوف يتجاوز الصفيف غير الفارغ القواعد أو رسائل الخطأ المخصصة المحددة بواسطة الفئة لهذا المثيل من الطريقة فقط.

ملاحظة: القيمة الافتراضية لـ $rules و $customMessages هي array() فارغة؛ وبالتالي، إذا قمت بتمرير array() فلن يتم تجاوز أي شيء.

رسائل خطأ التحقق المخصصة

تمامًا مثل Laravel Validator، يتيح لك Ardent تعيين رسائل خطأ مخصصة باستخدام نفس البنية.

 class User Extends LaravelArdentArdentArdent { public static $customMessages = array('required' => 'حقل السمة مطلوب.',
    ...
  );
}

قواعد التحقق المخصصة

يمكنك إنشاء قواعد تحقق مخصصة بنفس الطريقة التي تستخدمها مع Laravel Validator.

الخطافات النموذجية (منذ 2.0)

يوفر Ardent بعض السكر النحوي في أحداث نموذج Eloquent: خطافات النموذج التقليدية. إنها طريقة سهلة لربط العمليات الإضافية بلحظات مختلفة في حياتك النموذجية. ويمكن استخدامها للقيام بأعمال تنظيف إضافية قبل حذف الإدخال، أو إجراء إصلاحات تلقائية بعد حدوث التحقق من الصحة، أو تحديث النماذج ذات الصلة بعد حدوث التحديث.

كل ذلك before الخطافات، عند إرجاع false (على وجه التحديد القيم المنطقية، وليس مجرد القيم "الخاطئة") سوف يوقف العملية. لذلك، على سبيل المثال، إذا كنت تريد إيقاف الحفظ إذا حدث خطأ ما في طريقة beforeSave ، فما عليك سوى return false ولن يتم الحفظ - ومن الواضح أنه لن يتم استدعاء afterSave أيضًا.

فيما يلي القائمة الكاملة للخطافات المتاحة:

• before / afterCreate()

• before / afterSave()

• before / afterUpdate()

• before / afterDelete()

• before / afterValidate() - عندما يؤدي إرجاع false إلى إيقاف التحقق من الصحة، مما يؤدي إلى فشل عمليات save() أيضًا نظرًا لأن التحقق كان فاشلاً.

على سبيل المثال، يمكنك استخدام beforeSave لتجزئة كلمة مرور المستخدمين (في الواقع، سيكون من الأفضل استخدام التجزئة التلقائية!):

 فئة المستخدم يمتد LaravelArdentArdentArdent { public function beforeSave() {// إذا كانت هناك كلمة مرور جديدة، قم بتجزئة itif($this->isDirty('password')) { $this->password = Hash::make($this->password );
    } return true;// أو لا تُرجع أي شيء، لأن الخطأ المنطقي فقط هو الذي سيوقف العملية
  }
}

الإضافات قبل الحفظ وبعد الحفظ (منذ 1.0)

يمكن تضمين beforeSave و afterSave في وقت التشغيل. ما عليك سوى تمرير عمليات الإغلاق باستخدام النموذج كوسيطة للطريقة save() (أو forceSave() ).

 $user->save(array(), array(), array(), function ($model) { // إغلاق لـ beforeSaveecho "حفظ كائن النموذج...";return true;
  }, function ($model) { // إغلاق لـ afterSaveecho "done!";
  }
);

ملحوظة: يجب أن تحتوي عمليات الإغلاق على معلمة واحدة حيث سيتم تمرير مرجع إلى النموذج الذي يتم حفظه.

تعريف أنظف للعلاقات (منذ 2.0)

هل سبق لك أن كتبت نموذجًا Eloquent يحتوي على مجموعة من العلاقات، فقط لتلاحظ مدى ازدحام فصلك، مع كل تلك الأسطر التي تحتوي تقريبًا على نفس محتوى اسم الطريقة نفسها؟

في Ardent، يمكنك تحديد علاقاتك بشكل واضح في مصفوفة باستخدام معلوماتها، وستعمل تمامًا كما لو كنت قد حددتها في الأساليب. هنا مثال:

 فئة المستخدم يمتد LaravelArdentArdentArdent { public static $relationsData = array('address' => array(self::HAS_ONE, 'Address'),'orders' => array(self::HAS_MANY, 'Order'),'groups' = > المصفوفة (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 قادر على ترطيب فئة نموذج الكيان الخاص بك من إرسال إدخال النموذج تلقائيًا!

دعونا نرى ذلك العمل. خذ بعين الاعتبار مقتطف الكود هذا:

 $user = مستخدم جديد;$user->name = Input::get('name');$user->email = Input::get('email');$user->password = Hash::make(Input ::get('password'));$user->save();

فلنستدعي سحر Ardent ونعيد كتابة المقتطف السابق:

 $user = مستخدم جديد;$user->save();

هذا كل شيء! كل ما فعلناه هو إزالة الأشياء المملة.

صدق أو لا تصدق، الكود أعلاه يؤدي بشكل أساسي نفس المهمة التي يؤديها شقيقه الأكبر سنًا، وإن كان مطولًا إلى حد ما. يقوم Ardent بملء كائن النموذج بسمات من بيانات النموذج المقدمة من المستخدم. لا داعي للقلق من محاولة معرفة خاصية Eloquent التي نسيت أن تملأها. اسمح لـ Ardent بالاعتناء بالأشياء المملة، بينما تتابع أنت الأشياء الممتعة!
إنه يتبع نفس قواعد التعيين الجماعي داخليًا، اعتمادًا على خصائص $fillable / $guarded .

لتمكين ميزة الترطيب التلقائي، ما عليك سوى تعيين متغير المثيل $autoHydrateEntityFromInput على true في فئة النموذج الخاص بك. ومع ذلك، لمنع ملء الخصائص الموجودة مسبقًا، إذا كنت تريد الترطيب التلقائي أيضًا لسيناريوهات التحديث، فيجب عليك استخدام $forceEntityHydrationFromInput بدلاً من ذلك:

 class User Extends LaravelArdentArdentArdent { public $autoHydrateEntityFromInput = true;    // هيدرات عند التحقق من صحة الإدخالات الجديدة
  public $forceEntityHydrationFromInput = true; // هيدرات عندما يتم استدعاء التحقق من الصحة}

إزالة بيانات النموذج الزائدة تلقائيًا

يمكن للنماذج المتحمسة إزالة بيانات الإدخال الزائدة بطريقة سحرية (مثل تأكيد كلمة المرور أو _token CSRF المخفي أو حقول _method HTTP المخصصة) - بحيث لا يتم حفظ البيانات الإضافية في قاعدة البيانات أبدًا. سوف يستخدم Ardent حقول التأكيد للتحقق من صحة إدخال النموذج، ثم يتجاهل هذه السمات بحكمة قبل حفظ مثيل النموذج في قاعدة البيانات!

لتمكين هذه الميزة، ما عليك سوى تعيين متغير المثيل $autoPurgeRedundantAttributes إلى true في فئة النموذج الخاص بك:

 class User Extends LaravelArdentArdentArdent { public $autoPurgeRedundantAttributes = true;
}

يمكنك أيضًا مسح الحقول الإضافية. السمة Ardent::$purgeFilters عبارة عن مجموعة من عمليات الإغلاق التي يمكنك إضافة قواعدك المخصصة إليها. تتلقى عمليات الإغلاق هذه مفتاح السمة كوسيطة ويجب أن تُرجع false للسمات التي يجب إزالتها. مثله:

 وظيفة __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 :

 فئة المستخدم يمتد LaravelArdentArdentArdent { public static $passwordAttributes = array('password');  public $autoHashPasswordAttributes = true;
}

سيقوم Ardent تلقائيًا باستبدال سمة كلمة المرور ذات النص العادي بمجموع اختباري للتجزئة الآمنة وحفظها في قاعدة البيانات. يستخدم طريقة Laravel Hash::make() ‎ داخليًا لإنشاء التجزئة. ملاحظة: يُنصح باستخدام سمة Eloquent $hidden حتى لا تظهر كلمة المرور، حتى لو كانت مجزأة، بهذه السهولة إذا كنت تقوم بإنشاء واجهة برمجة تطبيقات أو ما شابه :)

في حالة استخدام Ardent المستقل، يمكنك استخدام Ardent::$hasher للتحقق من قيمة الحقل، باستخدام شيء مثل User::$hasher->check($given_password, $user->password) .

تحديثات بقواعد فريدة

يمكن لـ Ardent مساعدتك في التحديثات الفريدة. وفقًا لوثائق Laravel، عندما تقوم بتحديث (وبالتالي التحقق من صحة) حقل بقاعدة فريدة، يجب عليك تمرير المعرف الفريد للسجل الذي تقوم بتحديثه. بدون تمرير هذا المعرف، ستفشل عملية التحقق لأن أداة التحقق من Laravel ستعتقد أن هذا السجل مكرر.

من وثائق Laravel :

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

في الماضي، كان على المبرمجين إدارة تمرير المعرف يدويًا وتغيير مجموعة القواعد لتضمين المعرف في وقت التشغيل. ليس كذلك مع المتحمسين. ما عليك سوى إعداد القواعد الخاصة بك من خلال updateUniques وظيفة الاتصال unique ، وسوف يتولى Ardent الباقي.

مثال:

في النموذج الموسع الخاص بك، حدد القواعد الخاصة بك

  قواعد $ ثابتة عامة = صفيف( 'email' => 'مطلوب|بريد إلكتروني|فريد', 'كلمة المرور' => 'مطلوب|بين:4,20|مؤكد', 'password_confirmation' => 'بين:4,20',
  );

في وحدة التحكم الخاصة بك، عندما تحتاج إلى التحديث، ما عليك سوى الاتصال

 $model->updateUniques();

إذا لزم الأمر، يمكنك تمرير القواعد في وقت التشغيل إلى updateUniques ، وإلا فسيتم استخدام القواعد الثابتة التي يوفرها النموذج الخاص بك.

لاحظ أنه في مثال القواعد أعلاه، لم نخبر المدقق بالجدول أو حتى الحقل الذي يجب استخدامه كما هو موضح في وثائق Laravel (على سبيل المثال، unique:users,email,10 ). Ardent ذكي بما يكفي لمعرفة ذلك. (شكرًا لمستخدم جيثب @Sylph)