لاراول اسکاوت

• معرفی
• نصب و راه اندازی
  • در صف
• پیش نیاز راننده
  • الگوليا
  • Meilisearch
  • Typesense
• پیکربندی
  • پیکربندی شاخص های مدل
  • پیکربندی داده های قابل جستجو
  • پیکربندی شناسه مدل
  • پیکربندی موتورهای جستجو در هر مدل
  • شناسایی کاربران
• پایگاه داده / موتورهای مجموعه
  • موتور پایگاه داده
  • موتور مجموعه
• نمایه سازی
  • واردات دسته ای
  • اضافه کردن رکوردها
  • به روز رسانی سوابق
  • حذف رکوردها
  • توقف نمایه سازی
  • نمونه‌های مدل قابل جستجوی مشروط
• جستجوکردن
  • که در آن بندها
  • صفحه بندی
  • حذف نرم
  • سفارشی کردن جستجوهای موتور
• موتورهای سفارشی

معرفی

Laravel Scout یک راه حل ساده و مبتنی بر درایور برای افزودن جستجوی متن کامل به مدل های Eloquent شما ارائه می دهد . با استفاده از ناظران مدل، Scout به طور خودکار فهرست های جستجوی شما را با سوابق Eloquent شما هماهنگ می کند.

در حال حاضر، Scout با درایورهای Algolia ، Meilisearch ، Typesense و MySQL / PostgreSQL ( database ) ارسال می شود. علاوه بر این، Scout شامل یک درایور "مجموعه" است که برای استفاده توسعه محلی طراحی شده است و به هیچ گونه وابستگی خارجی یا خدمات شخص ثالث نیاز ندارد. علاوه بر این، نوشتن درایورهای سفارشی ساده است و شما می توانید Scout را با پیاده سازی های جستجوی خود گسترش دهید.

نصب و راه اندازی

ابتدا Scout را از طریق مدیریت بسته Composer نصب کنید:

composer require laravel/scout

پس از نصب Scout، باید فایل پیکربندی Scout را با استفاده از vendor:publish دستور Artisan منتشر کنید. این دستور scout.php فایل پیکربندی را در دایرکتوری برنامه شما منتشر می کند config :

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

در نهایت، Laravel\Scout\Searchable ویژگی را به مدلی که می‌خواهید قابل جستجو کنید، اضافه کنید. این ویژگی یک ناظر مدل را ثبت می کند که به طور خودکار مدل را با درایور جستجوی شما هماهنگ می کند:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class Post extends Model
{
    use Searchable;
}

در صف

در حالی که به شدت برای استفاده از Scout الزامی نیست، باید به شدت قبل از استفاده از کتابخانه پیکربندی درایور صف را در نظر بگیرید. اجرای یک queue worker به Scout اجازه می‌دهد تا تمام عملیات‌هایی را که اطلاعات مدل شما را با فهرست‌های جستجوی شما همگام‌سازی می‌کنند در صف قرار دهد و زمان پاسخ‌دهی بسیار بهتری را برای رابط وب برنامه شما فراهم کند.

هنگامی که یک درایور صف را پیکربندی کردید، مقدار گزینه موجود در فایل پیکربندی queue خود را به صورت زیر تنظیم کنید : config/scout.php true

'queue' => true,

حتی زمانی که این queue گزینه روی تنظیم شده است false ، مهم است که به یاد داشته باشید که برخی از رانندگان Scout مانند Algolia و Meilisearch همیشه رکوردها را به صورت ناهمزمان ایندکس می کنند. به این معنا که، حتی اگر عملیات ایندکس در برنامه لاراول شما کامل شده باشد، خود موتور جستجو ممکن است رکوردهای جدید و به روز شده را فوراً منعکس نکند.

برای مشخص کردن اتصال و صفی که مشاغل Scout شما از آن استفاده می کنند، می توانید queue گزینه پیکربندی را به عنوان یک آرایه تعریف کنید:

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

البته، اگر اتصال و صفی را که Scout Jobs از آن استفاده می‌کند سفارشی کنید، باید یک queue worker برای پردازش کارهای مربوط به آن اتصال و صف اجرا کنید:

php artisan queue:work redis --queue=scout

پیش نیاز راننده

الگوليا

هنگام استفاده از درایور Algolia، باید Algolia id و secret اعتبارنامه خود را در config/scout.php فایل پیکربندی خود پیکربندی کنید. هنگامی که اعتبار شما پیکربندی شد، همچنین باید Algolia PHP SDK را از طریق مدیر بسته Composer نصب کنید:

composer require algolia/algoliasearch-client-php

Meilisearch

Meilisearch یک موتور جستجوی فوق العاده سریع و منبع باز است. اگر مطمئن نیستید که چگونه Meilisearch را روی دستگاه محلی خود نصب کنید، می توانید از Laravel Sail ، محیط توسعه Docker لاراول که به طور رسمی پشتیبانی می شود، استفاده کنید.

هنگام استفاده از درایور Meilisearch، باید Meilisearch PHP SDK را از طریق مدیر بسته Composer نصب کنید:

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

سپس، SCOUT_DRIVER متغیر محیطی و همچنین Meilisearch host و key اعتبارنامه خود را در فایل برنامه خود تنظیم کنید .env :

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

برای اطلاعات بیشتر در مورد Meilisearch، لطفاً به اسناد Meilisearch مراجعه کنید .

meilisearch/meilisearch-php علاوه بر این، باید با بررسی اسناد Meilisearch در مورد سازگاری باینری ، اطمینان حاصل کنید که نسخه‌ای از آن را نصب می‌کنید که با نسخه باینری Meilisearch سازگار است .

هنگام ارتقاء Scout در برنامه‌ای که از Meilisearch استفاده می‌کند، همیشه باید هرگونه تغییر اضافی در خود سرویس Meilisearch را بررسی کنید.

Typesense

Typesense یک موتور جستجوی سریع و منبع باز است و از جستجوی کلمات کلیدی، جستجوی معنایی، جستجوی جغرافیایی و جستجوی برداری پشتیبانی می کند.

می‌توانید Typesense را خود میزبانی کنید یا از Typesense Cloud استفاده کنید .

برای شروع استفاده از Typesense با Scout، Typesense PHP SDK را از طریق مدیر بسته Composer نصب کنید:

composer require typesense/typesense-php

سپس، SCOUT_DRIVER متغیر محیطی و همچنین هاست Typesense و اعتبارنامه کلید API خود را در فایل env. برنامه خود تنظیم کنید:

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

در صورت نیاز، می توانید پورت، مسیر و پروتکل نصب خود را نیز مشخص کنید:

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

تنظیمات اضافی و تعاریف طرحواره برای مجموعه های Typesense شما را می توان در فایل پیکربندی برنامه شما یافت config/scout.php . برای اطلاعات بیشتر در مورد Typesense، لطفاً به اسناد Typesense مراجعه کنید .

آماده سازی داده ها برای ذخیره سازی در Typesense

هنگام استفاده از Typesense، مدل های قابل جستجو شما باید روشی را تعریف کنند toSearchableArray که کلید اصلی مدل شما را به یک رشته و تاریخ ایجاد را به مهر زمانی یونیکس می فرستد:

/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
public function toSearchableArray()
{
    return array_merge($this->toArray(),[
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

همچنین باید طرحواره های مجموعه Typesense خود را در فایل برنامه خود تعریف کنید config/scout.php . طرح واره مجموعه انواع داده های هر فیلد را که از طریق Typesense قابل جستجو هستند را توصیف می کند. برای اطلاعات بیشتر در مورد همه گزینه‌های طرحواره موجود، لطفاً به اسناد Typesense مراجعه کنید .

اگر شما نیاز به تغییر طرح مجموعه Typesense خود پس از تعریف دارید، می‌توانید scout:flush و را اجرا کنید scout:import ، که تمام داده‌های فهرست‌شده موجود را حذف کرده و طرح را دوباره ایجاد می‌کند. یا، می‌توانید از API Typesense برای اصلاح طرح مجموعه بدون حذف داده‌های نمایه‌شده استفاده کنید.

اگر مدل قابل جستجوی شما قابل حذف است، باید فیلدی را __soft_deleted در طرح Typesense مربوطه مدل در config/scout.php فایل پیکربندی برنامه خود تعریف کنید:

User::class => [
    'collection-schema' => [
        'fields' => [
            // ...
            [
                'name' => '__soft_deleted',
                'type' => 'int32',
                'optional' => true,
            ],
        ],
    ],
],

پارامترهای جستجوی پویا

Typesense به شما امکان می دهد پارامترهای جستجوی خود را به صورت پویا در هنگام انجام عملیات جستجو از طریق روش زیر تغییر دهید options :

use App\Models\Todo;
 
Todo::search('Groceries')->options([
    'query_by' => 'title, description'
])->get();

پیکربندی

پیکربندی شاخص های مدل

هر مدل Eloquent با یک «شاخص» جستجوی مشخص همگام‌سازی می‌شود که شامل تمام رکوردهای قابل جستجو برای آن مدل است. به عبارت دیگر، شما می توانید هر شاخص را مانند یک جدول MySQL در نظر بگیرید. به‌طور پیش‌فرض، هر مدل برای شاخصی که با نام «جدول» معمولی مدل مطابقت دارد، حفظ می‌شود. به طور معمول، این شکل جمع نام مدل است. با این حال، شما آزاد هستید که با نادیده گرفتن searchableAs روش روی مدل، شاخص مدل را سفارشی کنید :

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class Post extends Model
{
    use Searchable;
 
    /**
     * Get the name of the index associated with the model.
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

پیکربندی داده های قابل جستجو

به طور پیش فرض، کل toArray فرم یک مدل داده شده در فهرست جستجوی آن باقی می ماند. اگر می‌خواهید داده‌هایی را که با فهرست جستجو همگام‌سازی می‌شوند سفارشی کنید، می‌توانید toSearchableArray روش موجود در مدل را لغو کنید:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class Post extends Model
{
    use Searchable;
 
    /**
     * Get the indexable data array for the model.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();
 
        // Customize the data array...
 
        return $array;
    }
}

برخی از موتورهای جستجو مانند Meilisearch فقط عملیات فیلتر (، و غیره) را روی داده هایی از نوع صحیح انجام می > دهند < . بنابراین، هنگام استفاده از این موتورهای جستجو و سفارشی کردن داده‌های قابل جستجو، باید اطمینان حاصل کنید که مقادیر عددی به نوع صحیح خود ریخته می‌شوند:

public function toSearchableArray()
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

پیکربندی داده های قابل فیلتر و تنظیمات فهرست (Meilisearch)

برخلاف سایر درایورهای Scout، Meilisearch از شما می‌خواهد که تنظیمات جستجوی فهرست مانند ویژگی‌های قابل فیلتر، ویژگی‌های قابل مرتب‌سازی و سایر فیلدهای تنظیمات پشتیبانی‌شده را از قبل تعریف کنید .

ویژگی‌های قابل فیلتر، هر ویژگی هستند که می‌خواهید هنگام فراخوانی متد Scout روی آن‌ها فیلتر کنید ، در حالی که ویژگی‌های قابل مرتب‌سازی هر ویژگی هستند که قصد دارید هنگام فراخوانی روش where Scout آنها را مرتب کنید . orderBy برای تعریف تنظیمات فهرست خود، index-settings بخشی از ورودی پیکربندی خود را meilisearch در فایل پیکربندی برنامه خود تنظیم کنید scout :

use App\Models\User;
use App\Models\Flight;
 
'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes'=> ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
            // Other settings fields...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

اگر مدل زیر یک نمایه داده شده قابل حذف نرم باشد و در آرایه گنجانده شود index-settings ، Scout به طور خودکار از فیلتر کردن مدل های نرم حذف شده در آن شاخص پشتیبانی می کند. اگر هیچ صفت قابل فیلتر یا مرتب‌سازی دیگری برای تعریف یک شاخص مدل نرم‌افزاری ندارید، می‌توانید به سادگی یک ورودی خالی index-settings برای آن مدل به آرایه اضافه کنید:

'index-settings' => [
    Flight::class => []
],

پس از پیکربندی تنظیمات فهرست برنامه، باید scout:sync-index-settings دستور Artisan را فراخوانی کنید. این دستور Meilisearch را از تنظیمات فهرست پیکربندی فعلی شما مطلع می کند. برای راحتی، ممکن است بخواهید این دستور را بخشی از فرآیند استقرار خود کنید:

php artisan scout:sync-index-settings

پیکربندی شناسه مدل

به طور پیش فرض، Scout از کلید اصلی مدل به عنوان شناسه / کلید منحصر به فرد مدل استفاده می کند که در فهرست جستجو ذخیره می شود. اگر می‌خواهید این رفتار را سفارشی کنید، می‌توانید روش‌ها getScoutKey و getScoutKeyName روش‌های موجود در مدل را لغو کنید:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class User extends Model
{
    use Searchable;
 
    /**
     * Get the value used to index the model.
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }
 
    /**
     * Get the key name used to index the model.
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

پیکربندی موتورهای جستجو در هر مدل

scout هنگام جستجو، Scout معمولاً از موتور جستجوی پیش فرض مشخص شده در فایل پیکربندی برنامه شما استفاده می کند . با این حال، موتور جستجو برای یک مدل خاص را می توان با نادیده گرفتن searchableUsing روش روی مدل تغییر داد:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Engines\Engine;
use Laravel\Scout\EngineManager;
use Laravel\Scout\Searchable;
 
class User extends Model
{
    use Searchable;
 
    /**
     * Get the engine used to index the model.
     */
    public function searchableUsing(): Engine
    {
        return app(EngineManager::class)->engine('meilisearch');
    }
}

شناسایی کاربران

Scout همچنین به شما امکان می دهد هنگام استفاده از Algolia کاربران را به طور خودکار شناسایی کنید . مرتبط کردن کاربر احراز هویت شده با عملیات جستجو ممکن است هنگام مشاهده تجزیه و تحلیل جستجوی شما در داشبورد Algolia مفید باشد. می توانید با تعریف SCOUT_IDENTIFY متغیر محیطی مانند فایل true برنامه خود، شناسایی کاربر را فعال کنید .env :

SCOUT_IDENTIFY=true

فعال کردن این ویژگی همچنین آدرس IP درخواست و شناسه اصلی کاربر تأیید شده شما را به Algolia منتقل می کند، بنابراین این داده ها با هر درخواست جستجویی که توسط کاربر انجام می شود مرتبط می شود.

پایگاه داده / موتورهای مجموعه

موتور پایگاه داده

موتور پایگاه داده در حال حاضر از MySQL و PostgreSQL پشتیبانی می کند.

اگر برنامه شما با پایگاه داده های کوچک تا متوسط ​​تعامل دارد یا حجم کاری کمی دارد، ممکن است کار با موتور «پایگاه داده» Scout راحت تر باشد. موتور پایگاه داده هنگام فیلتر کردن نتایج از پایگاه داده موجود شما برای تعیین نتایج جستجوی قابل اجرا برای درخواست شما، از بندهای "where like" و نمایه های متن کامل استفاده می کند.

برای استفاده از موتور پایگاه داده، می‌توانید مقدار SCOUT_DRIVER متغیر محیطی را به سادگی تنظیم کنید database یا درایور را مستقیماً در فایل پیکربندی database برنامه خود مشخص کنید: scout

SCOUT_DRIVER=database

هنگامی که موتور پایگاه داده را به عنوان درایور ترجیحی خود مشخص کردید، باید داده های قابل جستجو خود را پیکربندی کنید . سپس، ممکن است شروع به اجرای عبارات جستجو بر اساس مدل های خود کنید. نمایه سازی موتورهای جستجو، مانند نمایه سازی مورد نیاز برای ایجاد نمایه های Algolia، Meilisearch یا Typesense، هنگام استفاده از موتور پایگاه داده غیر ضروری است.

سفارشی کردن استراتژی های جستجو در پایگاه داده

به طور پیش فرض، موتور پایگاه داده یک پرس و جو "where like" را در برابر هر ویژگی مدلی که به عنوان قابل جستجو پیکربندی کرده اید، اجرا می کند . با این حال، در برخی شرایط، این ممکن است منجر به عملکرد ضعیف شود. بنابراین، استراتژی جستجوی موتور پایگاه داده را می توان به گونه ای پیکربندی کرد که برخی از ستون های مشخص شده از عبارت های جستجوی متن کامل استفاده کنند یا فقط از محدودیت های "where like" برای جستجوی پیشوندهای رشته ها ( ) example% به جای جستجو در کل رشته ( %example% ) استفاده کنند.

برای تعریف این رفتار، می توانید ویژگی های PHP را به متد مدل خود اختصاص دهید toSearchableArray . هر ستونی که رفتار استراتژی جستجوی اضافی به آنها اختصاص داده نشده است، همچنان از استراتژی پیش‌فرض «where like» استفاده می‌کنند:

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;
 
/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

قبل از تعیین اینکه یک ستون باید از محدودیت‌های پرس و جوی متن کامل استفاده کند، مطمئن شوید که به ستون یک نمایه متن کامل اختصاص داده شده است .

موتور مجموعه

در حالی که شما آزاد هستید که از موتورهای جستجوی Algolia، Meilisearch یا Typesense در طول توسعه محلی استفاده کنید، ممکن است شروع کار با موتور "مجموعه" راحت تر باشد. موتور جمع‌آوری از جمله‌های "where" و فیلتر مجموعه بر روی نتایج پایگاه داده موجود شما برای تعیین نتایج جستجوی کاربردی برای درخواست شما استفاده می‌کند. هنگام استفاده از این موتور، لازم نیست مدل های قابل جستجوی خود را "نمایه" کنید، زیرا آنها به سادگی از پایگاه داده محلی شما بازیابی می شوند.

برای استفاده از موتور جمع‌آوری، می‌توانید به سادگی مقدار SCOUT_DRIVER متغیر محیطی را بر روی تنظیم کنید collection ، یا درایور را مستقیماً در فایل پیکربندی collection برنامه خود مشخص کنید: scout

SCOUT_DRIVER=collection

هنگامی که درایور مجموعه را به عنوان درایور ترجیحی خود مشخص کردید، می‌توانید درخواست‌های جستجو را بر اساس مدل‌های خود اجرا کنید. نمایه سازی موتورهای جستجو، مانند نمایه سازی مورد نیاز برای ایجاد نمایه های Algolia، Meilisearch یا Typesense، هنگام استفاده از موتور مجموعه غیر ضروری است.

تفاوت با موتور پایگاه داده

در نگاه اول، موتورهای "پایگاه داده" و "مجموعه ها" تقریباً مشابه هستند. هر دو به طور مستقیم با پایگاه داده شما برای بازیابی نتایج جستجو تعامل دارند. با این حال، موتور مجموعه از فهرست یا LIKE بندهای متن کامل برای یافتن رکوردهای منطبق استفاده نمی کند . در عوض، تمام رکوردهای ممکن را می کشد و از کمک کننده لاراول Str::is برای تعیین اینکه آیا رشته جستجو در مقادیر ویژگی مدل وجود دارد یا خیر استفاده می کند.

موتور مجموعه قابل حمل ترین موتور جستجو است زیرا در تمام پایگاه های داده رابطه ای پشتیبانی شده توسط لاراول (از جمله SQLite و SQL Server) کار می کند. با این حال، نسبت به موتور پایگاه داده Scout کارایی کمتری دارد.

نمایه سازی

واردات دسته ای

اگر Scout را در پروژه‌ای موجود نصب می‌کنید، ممکن است از قبل سوابق پایگاه داده‌ای داشته باشید که باید به فهرست‌های خود وارد کنید. Scout scout:import دستور Artisan را ارائه می دهد که می توانید از آن برای وارد کردن تمام رکوردهای موجود خود در فهرست های جستجوی خود استفاده کنید:

php artisan scout:import "App\Models\Post"

این flush دستور ممکن است برای حذف تمام رکوردهای یک مدل از فهرست های جستجوی شما استفاده شود:

php artisan scout:flush "App\Models\Post"

اصلاح درخواست واردات

اگر می‌خواهید پرس‌وجویی را که برای بازیابی همه مدل‌های شما برای وارد کردن دسته‌ای استفاده می‌شود، تغییر دهید، می‌توانید روشی را makeAllSearchableUsing روی مدل خود تعریف کنید. این یک مکان عالی برای اضافه کردن هرگونه بارگیری رابطه مشتاقانه ای است که ممکن است قبل از وارد کردن مدل های شما لازم باشد:

use Illuminate\Database\Eloquent\Builder;
 
/**
 * Modify the query used to retrieve models when making all of the models searchable.
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

این makeAllSearchableUsing روش ممکن است هنگام استفاده از صف برای مدل‌های واردات دسته‌ای قابل اجرا نباشد. وقتی مجموعه‌های مدل توسط کارها پردازش می‌شوند، روابط بازیابی نمی‌شوند .

اضافه کردن رکوردها

هنگامی که ویژگی را به یک مدل اضافه کردید Laravel\Scout\Searchable ، تنها کاری که باید انجام دهید این است save یا create یک نمونه مدل و به طور خودکار به فهرست جستجوی شما اضافه می شود. اگر Scout را برای استفاده از صف ها پیکربندی کرده اید، این عملیات در پس زمینه توسط کارگر صف شما انجام می شود:

use App\Models\Order;
 
$order = new Order;
 
// ...
 
$order->save();

افزودن سوابق از طریق Query

اگر می‌خواهید مجموعه‌ای از مدل‌ها را از طریق یک جستار Eloquent به فهرست جستجوی خود اضافه کنید، می‌توانید این searchable روش را به پرس و جوی Eloquent زنجیره بزنید. این searchable روش نتایج پرس و جو را تکه تکه می کند و رکوردها را به فهرست جستجوی شما اضافه می کند. مجدداً، اگر Scout را برای استفاده از صف ها پیکربندی کرده اید، همه تکه ها توسط کارگران صف شما در پس زمینه وارد می شوند:

use App\Models\Order;
 
Order::where('price', '>', 100)->searchable();

همچنین می‌توانید searchable روش را در یک نمونه رابطه Eloquent فراخوانی کنید:

$user->orders()->searchable();

یا اگر مجموعه‌ای از مدل‌های Eloquent را در حافظه دارید، می‌توانید متد را searchable در نمونه مجموعه فراخوانی کنید تا نمونه‌های مدل را به فهرست مربوطه‌شان اضافه کنید:

$orders->searchable();

این searchable روش را می توان یک عملیات "بالا" در نظر گرفت. به عبارت دیگر، اگر رکورد مدل از قبل در فهرست شما باشد، به روز می شود. اگر در فهرست جستجو وجود نداشته باشد، به فهرست اضافه می شود.

به روز رسانی سوابق

برای به روز رسانی یک مدل قابل جستجو، فقط باید ویژگی های نمونه مدل و save مدل را در پایگاه داده خود به روز کنید. Scout به طور خودکار تغییرات فهرست جستجوی شما را ادامه می دهد:

use App\Models\Order;
 
$order = Order::find(1);
 
// Update the order...
 
$order->save();

همچنین می‌توانید searchable متد را در یک نمونه پرس و جوی Eloquent برای به‌روزرسانی مجموعه‌ای از مدل‌ها فراخوانی کنید. اگر مدل‌ها در فهرست جستجوی شما وجود نداشته باشند، ایجاد می‌شوند:

Order::where('price', '>', 100)->searchable();

اگر می‌خواهید رکوردهای فهرست جستجو را برای همه مدل‌های موجود در یک رابطه به‌روزرسانی کنید، می‌توانید searchable از نمونه رابطه استفاده کنید:

$user->orders()->searchable();

یا اگر مجموعه‌ای از مدل‌های Eloquent را در حافظه دارید، می‌توانید متد را searchable در نمونه مجموعه فراخوانی کنید تا نمونه‌های مدل را در فهرست مربوطه به‌روزرسانی کنید:

$orders->searchable();

اصلاح سوابق قبل از واردات

گاهی اوقات ممکن است لازم باشد مجموعه ای از مدل ها را قبل از اینکه قابل جستجو شوند، آماده کنید. به عنوان مثال، ممکن است بخواهید مشتاقانه یک رابطه را بارگیری کنید تا داده های رابطه به طور موثر به فهرست جستجوی شما اضافه شوند. برای انجام این کار، یک makeSearchableUsing متد در مدل مربوطه تعریف کنید:

use Illuminate\Database\Eloquent\Collection;
 
/**
 * Modify the collection of models being made searchable.
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

حذف رکوردها

برای حذف یک رکورد از فهرست خود، می توانید به سادگی delete مدل را از پایگاه داده تهیه کنید. این ممکن است حتی اگر از مدل‌های حذف شده نرم استفاده می‌کنید انجام شود :

use App\Models\Order;
 
$order = Order::find(1);
 
$order->delete();

اگر نمی‌خواهید مدل را قبل از حذف رکورد بازیابی کنید، می‌توانید از این unsearchable روش در یک نمونه پرس و جو Eloquent استفاده کنید:

Order::where('price', '>', 100)->unsearchable();

اگر می‌خواهید رکوردهای فهرست جستجو را برای همه مدل‌های موجود در یک رابطه حذف کنید، می‌توانید از unsearchable مثال روی رابطه استفاده کنید:

$user->orders()->unsearchable();

یا اگر مجموعه‌ای از مدل‌های Eloquent در حافظه دارید، می‌توانید متد را unsearchable در نمونه مجموعه فراخوانی کنید تا نمونه‌های مدل را از فهرست مربوطه حذف کنید:

$orders->unsearchable();

توقف نمایه سازی

گاهی اوقات ممکن است لازم باشد دسته ای از عملیات Eloquent را روی یک مدل بدون همگام سازی داده های مدل با فهرست جستجوی خود انجام دهید. می توانید این کار را با استفاده از withoutSyncingToSearch روش انجام دهید. این روش یک بسته شدن را می پذیرد که بلافاصله اجرا می شود. هر گونه عملیات مدلی که در بسته شدن رخ می دهد با شاخص مدل همگام سازی نمی شود:

use App\Models\Order;
 
Order::withoutSyncingToSearch(function () {
    // Perform model actions...
});

نمونه‌های مدل قابل جستجوی مشروط

گاهی اوقات ممکن است نیاز داشته باشید که فقط یک مدل را تحت شرایط خاصی قابل جستجو کنید. برای مثال، تصور کنید مدلی دارید App\Models\Post که ممکن است در یکی از دو حالت باشد: «پیش‌نویس» و «منتشر شده». ممکن است بخواهید فقط به پست های «منتشر شده» اجازه جستجو داشته باشید. برای انجام این کار، ممکن است shouldBeSearchable روشی را در مدل خود تعریف کنید:

/**
 * Determine if the model should be searchable.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

این shouldBeSearchable روش تنها زمانی اعمال می شود که مدل ها را از طریق save و create متدها، پرس و جوها یا روابط دستکاری کنید. ایجاد مستقیم مدل‌ها یا مجموعه‌هایی که با استفاده از searchable روش قابل جستجو هستند، نتیجه shouldBeSearchable روش را لغو می‌کند.

این shouldBeSearchable روش هنگام استفاده از موتور "پایگاه داده" Scout قابل اجرا نیست، زیرا همه داده های قابل جستجو همیشه در پایگاه داده ذخیره می شوند. برای دستیابی به رفتار مشابه در هنگام استفاده از موتور پایگاه داده، باید به جای آن از بند های Where استفاده کنید .

جستجوکردن

می توانید با استفاده از این search روش جستجوی یک مدل را آغاز کنید. روش جستجو یک رشته واحد را می پذیرد که برای جستجوی مدل های شما استفاده می شود. سپس باید get متد را به پرس و جوی جستجو زنجیر کنید تا مدل های Eloquent را که با عبارت جستجوی داده شده مطابقت دارند بازیابی کنید:

use App\Models\Order;
 
$orders = Order::search('Star Trek')->get();

از آنجایی که جستجوهای Scout مجموعه‌ای از مدل‌های Eloquent را برمی‌گردانند، حتی ممکن است نتایج را مستقیماً از یک مسیر یا کنترل‌کننده برگردانید و به‌طور خودکار به JSON تبدیل می‌شوند:

use App\Models\Order;
use Illuminate\Http\Request;
 
Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

اگر می‌خواهید نتایج جستجوی خام را قبل از تبدیل به مدل‌های Eloquent دریافت کنید، می‌توانید از raw روش زیر استفاده کنید:

$orders = Order::search('Star Trek')->raw();

شاخص های سفارشی

پرس و جوهای جستجو معمولاً بر روی شاخص مشخص شده توسط روش مدل انجام می شود searchableAs . با این حال، می توانید از این within روش برای تعیین یک شاخص سفارشی استفاده کنید که به جای آن باید جستجو شود:

$orders = Order::search('Star Trek')
    ->within('tv_shows_popularity_desc')
    ->get();

که در آن بندها

Scout به شما این امکان را می دهد که بندهای ساده "where" را به عبارت های جستجوی خود اضافه کنید. در حال حاضر، این بندها فقط از بررسی‌های برابری عددی اولیه پشتیبانی می‌کنند و در درجه اول برای جستجوی محدوده جستجو توسط شناسه مالک مفید هستند:

use App\Models\Order;
 
$orders = Order::search('Star Trek')->where('user_id', 1)->get();

علاوه بر این، این whereIn روش ممکن است برای تأیید اینکه مقدار یک ستون معین در آرایه داده شده وجود دارد استفاده شود:

$orders = Order::search('Star Trek')->whereIn(
    'status', ['open', 'paid']
)->get();

این whereNotIn روش تأیید می کند که مقدار ستون داده شده در آرایه داده شده وجود ندارد:

$orders = Order::search('Star Trek')->whereNotIn(
    'status', ['closed']
)->get();

از آنجایی که یک فهرست جستجو یک پایگاه داده رابطه‌ای نیست، جملات پیشرفته‌تر «where» در حال حاضر پشتیبانی نمی‌شوند.

اگر برنامه شما از Meilisearch استفاده می کند، باید قبل از استفاده از بندهای "where" Scout، ویژگی های قابل فیلتر برنامه خود را پیکربندی کنید .

صفحه بندی

علاوه بر بازیابی مجموعه ای از مدل ها، می توانید نتایج جستجوی خود را با استفاده از این paginate روش صفحه بندی کنید. این متد یک نمونه را برمی گرداند Illuminate\Pagination\LengthAwarePaginator درست مثل اینکه یک پرس و جو سنتی Eloquent را صفحه بندی کرده باشید :

use App\Models\Order;
 
$orders = Order::search('Star Trek')->paginate();

می توانید با ارسال مقدار به عنوان اولین آرگومان به paginate متد، تعداد مدل های بازیابی در هر صفحه را مشخص کنید:

$orders = Order::search('Star Trek')->paginate(15);

هنگامی که نتایج را بازیابی کردید، می توانید نتایج را نمایش دهید و پیوندهای صفحه را با استفاده از Blade ارائه دهید ، درست مثل اینکه یک پرس و جو سنتی Eloquent را صفحه بندی کرده اید:

<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>
 
{{ $orders->links() }}

البته، اگر می‌خواهید نتایج صفحه‌بندی را به‌صورت JSON بازیابی کنید، می‌توانید نمونه صفحه‌بندی را مستقیماً از یک مسیر یا کنترلر برگردانید:

use App\Models\Order;
use Illuminate\Http\Request;
 
Route::get('/orders', function (Request $request) {
    return Order::search($request->input('query'))->paginate(15);
});

از آنجایی که موتورهای جستجو از تعاریف دامنه جهانی مدل Eloquent شما آگاه نیستند، نباید از دامنه جهانی در برنامه هایی که از صفحه بندی Scout استفاده می کنند استفاده کنید. یا، هنگام جستجو از طریق Scout، باید محدودیت‌های دامنه جهانی را دوباره ایجاد کنید.

حذف نرم

اگر مدل‌های نمایه‌شده شما در حال حذف نرم‌افزاری هستند و باید مدل‌های حذف شده نرم‌افزاری خود را جستجو کنید، soft_delete گزینه config/scout.php فایل پیکربندی را روی true :

'soft_delete' => true,

وقتی این گزینه پیکربندی است true ، Scout مدل های نرم حذف شده را از فهرست جستجو حذف نمی کند. در عوض، یک __soft_deleted ویژگی پنهان در رکورد ایندکس شده تنظیم می کند . سپس، می‌توانید از روش‌های withTrashed یا onlyTrashed برای بازیابی سوابق پاک‌شده نرم هنگام جستجو استفاده کنید:

use App\Models\Order;
 
// Include trashed records when retrieving results...
$orders = Order::search('Star Trek')->withTrashed()->get();
 
// Only include trashed records when retrieving results...
$orders = Order::search('Star Trek')->onlyTrashed()->get();

هنگامی که یک مدل نرم افزاری حذف شده برای همیشه با استفاده از حذف شود forceDelete ، Scout آن را به طور خودکار از فهرست جستجو حذف می کند.

سفارشی کردن جستجوهای موتور

اگر نیاز به سفارشی‌سازی پیشرفته رفتار جستجوی یک موتور دارید، ممکن است بسته شدن را به عنوان آرگومان دوم برای search روش ارسال کنید. برای مثال، می‌توانید از این تماس برای اضافه کردن داده‌های موقعیت جغرافیایی به گزینه‌های جستجوی خود قبل از ارسال عبارت جستجو به Algolia استفاده کنید:

use Algolia\AlgoliaSearch\SearchIndex;
use App\Models\Order;
 
Order::search(
    'Star Trek',
    function (SearchIndex $algolia, string $query, array $options) {
        $options['body']['query']['bool']['filter']['geo_distance'] = [
            'distance' => '1000km',
            'location' => ['lat' => 36, 'lon' => 111],
        ];
 
        return $algolia->search($query, $options);
    }
)->get();

سفارشی کردن پرس و جو نتایج Eloquent

پس از اینکه Scout لیستی از مدل های Eloquent منطبق را از موتور جستجوی برنامه شما بازیابی کرد، Eloquent برای بازیابی همه مدل های مطابق با کلیدهای اصلی آنها استفاده می شود. شما می توانید این پرس و جو را با فراخوانی query روش سفارشی کنید. این query متد بسته‌ای را می‌پذیرد که نمونه سازنده کوئری Eloquent را به عنوان آرگومان دریافت می‌کند:

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;
 
$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

از آنجایی که این فراخوانی پس از بازیابی مدل های مربوطه از موتور جستجوی برنامه شما فراخوانی می شود، این query روش نباید برای "فیلتر کردن" نتایج استفاده شود. در عوض، باید از Scout where clauses استفاده کنید .

موتورهای سفارشی

نوشتن موتور

اگر یکی از موتورهای جستجوی داخلی Scout با نیازهای شما مطابقت ندارد، می توانید موتور سفارشی خود را بنویسید و آن را در Scout ثبت کنید. موتور شما باید Laravel\Scout\Engines\Engine کلاس انتزاعی را گسترش دهد. این کلاس انتزاعی شامل هشت روش است که موتور سفارشی شما باید اجرا کند:

use Laravel\Scout\Builder;
 
abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);

ممکن است بررسی پیاده سازی این متدها در Laravel\Scout\Engines\AlgoliaEngine کلاس مفید باشد. این کلاس نقطه شروع خوبی را برای یادگیری نحوه پیاده سازی هر یک از این روش ها در موتور خود به شما ارائه می دهد.

ثبت موتور

هنگامی که موتور سفارشی خود را نوشتید، می توانید آن را با استفاده از extend روش مدیر موتور پیشاهنگ در Scout ثبت کنید. مدیر موتور Scout ممکن است از ظرف سرویس لاراول حل شود. شما باید extend متد را از boot متد کلاس خود App\Providers\AppServiceProvider یا هر ارائه دهنده سرویس دیگری که توسط برنامه شما استفاده می شود فراخوانی کنید:

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

هنگامی که موتور شما ثبت شد، می توانید آن را به عنوان Scout پیش فرض خود در فایل پیکربندی driver برنامه خود مشخص کنید: config/scout.php

'driver' => 'mysql',