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

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

معرفی

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

در حال حاضر، Scout با راننده Algolia حمل می کند . با این حال، نوشتن درایورهای سفارشی ساده است و شما می توانید Scout را با پیاده سازی های جستجوی خود گسترش دهید.

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

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

composer require laravel/scout:^8.0

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

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

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

<?php
 
namespace App;
 
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,

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

الگوليا

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

composer require algolia/algoliasearch-client-php:^2.2

پیکربندی

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

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

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

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

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

<?php
 
namespace App;
 
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
     */
    public function toSearchableArray()
    {
        $array = $this->toArray();
 
        // Customize array...
 
        return $array;
    }
}

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

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

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

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

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

SCOUT_IDENTIFY=true

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

نمایه سازی

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

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

php artisan scout:import "App\Post"

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

php artisan scout:flush "App\Post"

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

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

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

افزودن از طریق پرس و جو

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

// Adding via Eloquent query...
App\Order::where('price', '>', 100)->searchable();
 
// You may also add records via relationships...
$user->orders()->searchable();
 
// You may also add records via collections...
$orders->searchable();

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

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

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

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

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

// Updating via Eloquent query...
App\Order::where('price', '>', 100)->searchable();
 
// You may also update via relationships...
$user->orders()->searchable();
 
// You may also update via collections...
$orders->searchable();

حذف رکوردها

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

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

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

// Removing via Eloquent query...
App\Order::where('price', '>', 100)->unsearchable();
 
// You may also remove via relationships...
$user->orders()->unsearchable();
 
// You may also remove via collections...
$orders->unsearchable();

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

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

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

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

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

public function shouldBeSearchable()
{
    return $this->isPublished();
}

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

// Will respect "shouldBeSearchable"...
App\Order::where('price', '>', 100)->searchable();
 
$user->orders()->searchable();
 
$order->save();
 
// Will override "shouldBeSearchable"...
$orders->searchable();
 
$order->searchable();

جستجوکردن

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

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

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

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

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

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

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

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

که در آن بندها

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

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

صفحه بندی

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

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

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

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

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

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

حذف نرم

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

'soft_delete' => true,

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

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

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

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

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

use Algolia\AlgoliaSearch\SearchIndex;
 
App\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();

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

نوشتن موتور

اگر یکی از موتورهای جستجوی داخلی 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 ثبت کنید. شما باید extend روش را از boot روش خود AppServiceProvider یا هر ارائه دهنده خدمات دیگری که توسط برنامه شما استفاده می شود فراخوانی کنید. به عنوان مثال، اگر شما نوشته اید MySqlSearchEngine ، می توانید آن را به این صورت ثبت کنید:

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

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

'driver' => 'mysql',

ماکروهای سازنده

اگر می خواهید یک متد سازنده سفارشی تعریف کنید، می توانید از macro متد در Laravel\Scout\Builder کلاس استفاده کنید. به طور معمول، "ماکروها" باید در روش ارائه دهنده خدمات تعریف شوند boot :

<?php
 
namespace App\Providers;
 
use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;
use Laravel\Scout\Builder;
 
class ScoutMacroServiceProvider extends ServiceProvider
{
    /**
     * Register the application's scout macros.
     *
     * @return void
     */
    public function boot()
    {
        Builder::macro('count', function () {
            return $this->engine->getTotalCount(
                $this->engine()->search($this)
            );
        });
    }
}

تابع macro یک نام را به عنوان اولین آرگومان خود و یک Closure را به عنوان دومین آرگومان خود می پذیرد. هنگام فراخوانی نام ماکرو از یک Laravel\Scout\Builder پیاده سازی، بسته شدن ماکرو اجرا می شود:

App\Order::search('Star Trek')->count();