searchable

سمة قابلة للبحث في نماذج Laravel Eloquent

تضيف هذه الحزمة وظيفة البحث/التصفية إلى نماذج Eloquent في Laravel 4/5/6.

يمكنك أيضًا أن تجد هذه الحزم مفيدة:

• Withable - يسمح بالتحميل المتلهف للعلاقات باستخدام معلمات الطلب
• قابل للفرز - يسمح بفرز النماذج الخاصة بك باستخدام معلمات الطلب
• Pimpable - حزمة تعريفية تجمع بين السلوكيات القابلة للفرز والقابلة للبحث والقابلة للقابلية

تثبيت الملحن

أضف السطر التالي إلى ملف composer.json في مشروعك:

 "jedrzej/searchable": "0.0.17"

أو قم بتشغيل ما يلي في سطر الأوامر في المجلد الجذر لمشروعك:

 composer require "jedrzej/searchable" "0.0.17"

إعداد نماذج قابلة للبحث

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

 use Jedrzej  Searchable  SearchableTrait ;

class Post extends Eloquent
{
	use SearchableTrait ;
	
	// either a property holding a list of searchable fields...
	public $ searchable = [ ' title ' , ' forum_id ' , ' user_id ' , ' created_at ' ];
	
	// ...or a method that returns a list of searchable fields
	public function getSearchableAttributes ()
	{
	    return [ ' title ' , ' forum_id ' , ' user_id ' , ' created_at ' ];
	}
}

لجعل جميع الحقول قابلة للبحث، ضع علامة النجمة * في قائمة الحقول القابلة للبحث:

 public $ searchable = [ ' * ' ];

من الممكن أيضًا إدراج سمات النموذج في القائمة السوداء لمنع تصفيتها.

يمكنك إما تحديد خاصية $notSearchable أو تنفيذ طريقة getNotSearchableAttributes إذا كنت تريد تنفيذ بعض المنطق لتحديد قائمة الحقول القابلة للبحث.

 use Jedrzej  Searchable  SearchableTrait ;

class Post extends Eloquent
{
	use SearchableTrait ;
	
	// either a property holding a list of not searchable fields...
	public $ notSearchable = [ ' created_at ' ];
	
	// ...or a method that returns a list of not searchable fields
	public function getNotSearchableAttributes ()
	{
	    return [ ' created_at ' ];
	}
}

إذا قمت بتحديد كلتا القائمتين - الأعمدة القابلة للبحث وغير القابلة للبحث - فإن المجموعة الناتجة من الحقول القابلة للبحث ستحتوي على جميع السمات المدرجة في القائمة البيضاء باستثناء جميع السمات المدرجة في القائمة السوداء.

نماذج البحث

يضيف SearchableTrait نطاقًا filtered() إلى النموذج - يمكنك تمرير استعلام إليه باعتباره مصفوفة من شروط التصفية:

 // return all posts with forum_id equal to $forum_id
Post :: filtered ([ ' forum_id ' => $ forum_id ])-> get ();

// return all posts with with <operator> applied to forum_id
Post :: filtered ([ ' forum_id ' => <operator>])-> get ();

أو سيستخدم Request::all() كإعداد افتراضي:

 // if you append ?forum_id=<operator> to the URL, you'll get all Posts with <operator> applied to forum_id
Post :: filtered ()-> get ();

اختيار وضع الاستعلام

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

بناء استعلام

يدعم SearchableTrait عوامل التشغيل التالية:

عوامل المقارنة

تسمح عوامل المقارنة بالتصفية بناءً على نتيجة المقارنة بين سمة النموذج وقيمة الاستعلام. أنها تعمل للسلاسل والأرقام والتواريخ. لديهم التنسيق التالي:

 (<operator>)<value>

عوامل المقارنة التالية متاحة:

• gt greater than المقارنة
• ge للمقارنة greater than or equal
• lt less than المقارنة، على سبيل المثال
• le للمقارنة les than or equal

لتصفية المشاركات من عام 2015 وما فوق، يجب استخدام الاستعلام التالي:

 ?created_at=(ge)2015-01-01

يساوي/في عوامل التشغيل

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

من أجل تصفية المشاركات من المستخدم بالمعرف 42، يجب استخدام الاستعلام التالي:

 ?user_id=42

لتصفية المشاركات من المنتديات ذات المعرف 7 أو 8، يجب استخدام الاستعلام التالي:

 ?forum_id=7,8

مثل المشغلين

تسمح عوامل التشغيل بالتصفية باستخدام استعلام LIKE . يتم تشغيل عامل التشغيل هذا في حالة استخدام عامل المطابقة التامة، ولكن القيمة تحتوي على علامة % كحرف أول أو أخير.

لتصفية المشاركات التي تبدأ بـ How ، يجب استخدام الاستعلام التالي:

 ?title=How%

Notice: يتم استخدام حرف النسبة المئوية لترميز الأحرف الخاصة في عناوين URL، لذلك عند إرسال الطلب تأكد من أن الأدوات التي تستخدمها تقوم بشكل صحيح encode the % character as %25

عامل تشغيل فارغ

يسمح عامل التشغيل Null (null) بتصفية النماذج التي تكون سمتها فارغة.

لتصفية المشاركات التي لا تحتوي على مرفقات، يجب استخدام الاستعلام التالي:

 ?attachment_id=(null)

عامل النفي

من الممكن الحصول على نتائج مرفوضة للاستعلام عن طريق تعليق عامل التشغيل مسبقًا بـ ! .

بعض الأمثلة:

 //filter posts from all forums except those with id 7 or 8
?forum_id=!7,8

//filter posts older than 2015
?created_at=!(ge)2015

//filter posts with attachment
?attachment_id=!(null)

قيود متعددة لسمة واحدة

من الممكن تطبيق قيود متعددة على سمة نموذج واحد. لتحقيق ذلك، قم بتوفير مجموعة من مرشحات الاستعلام بدلاً من مرشح واحد:

 // filter all posts from year 20** except 2013
?created_at[]=20%&created_at[]=!2013%

التصفية حسب سمات العلاقة

من الممكن التصفية حسب سمات علاقات النموذج - سيتم تطبيق Eloquent's whereHas() . من أجل التصفية حسب العلاقة، قم بإضافة سمة العلاقة إلى قائمة الحقول searchable في النموذج relation:attribute . يجب استخدام نفس السلسلة في الاستعلام للتصفية حسب سمة تلك العلاقة، على سبيل المثال:

 // allow filtering on user's active field
 protected $searchable = ['user:active'];

 // filter only posts of active users
 ?user:active=1

من الممكن أيضًا إلغاء كائنات البحث والتصفية التي ليس لها علاقة مطابقة عن طريق تطبيق Eloquent's whereDoesntHave() . من أجل القيام بذلك، قم ببادئة اسم العلاقة بـ ! :

 // allow filtering on comment's approved field
 protected $searchable = ['comments:approved'];

 // filter only posts that have approved comments
 ?comments:approved=1
      
 // filter only posts that have not-approved comments
 ?comments:approved=1
 
 // filter only posts that do not have approved comments
 ?!comments:approved=1

إذا كنت تريد التصفية حسب علاقة متداخلة، فما عليك سوى توفير اسم العلاقة المتداخلة مع استبدال النقطة بنقطتين. يعد ذلك ضروريًا لأن PHP تقوم تلقائيًا باستبدال النقاط بشرطات سفلية في عنوان URL.

 // filter only posts that have comments from active authors
 ?comments:author:active=1

تجاوز منطق التصفية الافتراضي

من الممكن معالجة المرشحات المحددة باستخدام المنطق الخاص بك، على سبيل المثال، عندما لا يتطابق اسم المرشح مع اسم السمة المستخدمة للتصفية أو عندما يلزم تنفيذ بعض العمليات المخصصة. لتجاوز منطق عامل التصفية xyz ، ستحتاج إلى تحديد طريقة في النموذج الخاص بك تسمى processXyzFilter . يجب أن تُرجع هذه الطريقة true ، إذا تمت معالجة عامل التصفية ولم يعد المنطق الافتراضي يحدث.

 // use one filter to search in multiple columns
 protected function processNameFilter ( Builder $ builder , Constraint $ constraint )
 {
     // this logic should happen for LIKE/EQUAL operators only
     if ( $ constraint -> getOperator () === Constraint :: OPERATOR_LIKE || $ constraint -> getOperator () === Constraint :: OPERATOR_EQUAL ) {
         $ builder -> where ( function ( $ query ) use ( $ constraint ) {
             $ query -> where ( ' first_name ' , $ constraint -> getOperator (), $ constraint -> getValue ())
                 -> orWhere ( ' last_name ' , $ constraint -> getOperator (), $ constraint -> getValue ());
         });

         return true ;
     }

     // default logic should be executed otherwise
     return false ;
 }

لتجاوز عامل التصفية للبحث عن العلاقة، استبدل النقطتين في اسم الفلتر بشرطة سفلية. إذا أردت تجاوز المنطق الخاص بـ user:active ، فستحتاج إلى تحديد طريقة processUser_ActiveFilter .