‏Elastic Bridge؛ کوئری Elasticsearch به سبک Eloquent

به نوشتهٔ Laravel News، پکیج Elastic Bridge ساختهٔ Agyenim Boateng می‌ذاره به Elasticsearch و OpenSearch با یه API شبیه Eloquent کوئری بزنی. یعنی دیگه لازم نیست JSON DSL (همون ساختار JSONی که خود موتور جست‌وجو برای کوئری می‌خواد) رو دستی سر هم کنی. پکیج کلاس‌های مدلش رو bridge صدا می‌زنه و با php artisan make:bridge یکی می‌سازی؛ هر bridge از کلاس پایهٔ پکیج ارث می‌بره و با پراپرتی $index می‌گی به کدوم ایندکس وصله.

کار اصلی همین زنجیره کردن متدهاست. تو یه کوئری هم match متنی می‌زنی، هم فیلتر دقیق، هم بازهٔ قیمت و مرتب‌سازی و صفحه‌بندی:

$rooms = HotelRoom::asBoolean()
    ->mustMatch('city', 'accra')
    ->filterByTerm('code', 'usd')
    ->filterByRange('price', 500, 'lte')
    ->orderBy('price', 'ASC')
    ->cursorPaginate(15)
    ->get(['name', 'price', 'code']);

فرق mustMatch() و filterByTerm() همون فرقیه که خود موتور جست‌وجو می‌ذاره: اولی یه بند match می‌سازه، دومی یه فیلتر term دقیق. برای جست‌وجو روی چند فیلد هم multiMatch() هست که تو نسخهٔ 2 خودش به‌طور خودکار داخل یه کوئری boolean می‌ره. صفحه‌بندی مبتنی بر cursor از search_after استفاده می‌کنه و به یه مرتب‌سازی قطعی نیاز داره؛ مقدارهای بعدی و قبلی رو از links() می‌گیری و همونو به cursorPaginate() بعدی پاس می‌دی.

سمت تجمیع، متدهای ساده‌ای مثل avg() و sum() و count() داری و می‌تونی با withAggregate() یه تجمیع رو به کوئری سند بچسبونی. تو نسخهٔ 2 نتیجهٔ تجمیع مال همون کالکشن برگشتیه، پس دو تا نتیجهٔ جدا مقدارهای خودشونو نگه می‌دارن، حتی تو ورکرهای طولانی‌مدت. stats() یه آبجکت Stats برمی‌گردونه و histogram() یه کالکشن از باکت‌ها.

برای تست هم لازم نیست Elasticsearch بالا بیاری: متد fake() یه پاسخ جست‌وجوی ساختگی می‌ده و با toQuery() می‌تونی کوئری‌ای که اپلیکیشنت ساخته رو نگاه کنی و assert بزنی. یعنی تست‌های کوئری‌ت روی CI بدون کلاستر هم سبز می‌شن.

نیازمندی‌های مستندشده PHP نسخهٔ 8.2 یا 8.3، لاراول 10 و 11 و 12، و Elasticsearch 8.x یا OpenSearch 2.x هست. بعد از نصب با composer، متغیر SEARCH_DRIVER رو روی elasticsearch یا opensearch می‌ذاری و اتصال رو تو config/elasticbridge.php تنظیم می‌کنی؛ هر دو درایور همون API یکسان رو دارن. احراز هویت هم basic auth و API key داره، به‌علاوهٔ AWS SigV4 برای OpenSearch. پکیج راهنما و skill مخصوص Laravel Boost هم داره و با MIT روی گیت‌هاب منتشر شده.

نکات کلیدی:

• کلاس‌های مدل پکیج اسمشون bridge هست و با php artisan make:bridge ساخته می‌شن.
• نسخهٔ 2: multiMatch() و matchPhrase() خودکار داخل کوئری boolean قرار می‌گیرن و نتیجهٔ تجمیع به کالکشن برگشتی چسبیده.
• صفحه‌بندی cursor روی search_after سواره و مرتب‌سازی قطعی لازم داره.
• fake() و toQuery() تست بدون کلاستر واقعی رو ممکن می‌کنن.
• نیازمندی‌ها: PHP 8.2/8.3، لاراول 10 تا 12، Elasticsearch 8.x یا OpenSearch 2.x؛ لایسنس MIT.