Package Data | |
---|---|
Maintainer Username: | pmatseykanets |
Maintainer Contact: | pmatseykanets@gmail.com (Peter Matseykanets) |
Package Create Date: | 2016-09-02 |
Package Last Update: | 2023-04-28 |
Home Page: | |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2024-12-19 03:20:40 |
Package Statistics | |
---|---|
Total Downloads: | 191,724 |
Monthly Downloads: | 905 |
Daily Downloads: | 16 |
Total Stars: | 161 |
Total Watchers: | 5 |
Total Forks: | 39 |
Total Open Issues: | 18 |
This package makes it easy to use native PostgreSQL Full Text Search capabilities with Laravel Scout.
You can install the package via composer:
Scout 7
composer require pmatseykanets/laravel-scout-postgres
Scout 6
composer require pmatseykanets/laravel-scout-postgres:4.0.0
Scout 5
composer require pmatseykanets/laravel-scout-postgres:3.1.0
Scout 4
composer require pmatseykanets/laravel-scout-postgres:2.3.0
Scout 2, 3
composer require pmatseykanets/laravel-scout-postgres:1.0.0
Scout 1
composer require pmatseykanets/laravel-scout-postgres:0.2.1
If you're using Laravel < 5.5 or if you have package auto-discovery turned off you have to manually register the service provider:
// config/app.php
'providers' => [
...
ScoutEngines\Postgres\PostgresEngineServiceProvider::class,
],
Scout service provider uses config_path
helper that is not included in the Lumen.
To fix this include the following snippet either directly in bootstrap.app
or in your autoloaded helpers file i.e. app/helpers.php
.
if (! function_exists('config_path')) {
/**
* Get the configuration path.
*
* @param string $path
* @return string
*/
function config_path($path = '')
{
return app()->basePath() . '/config'.($path ? DIRECTORY_SEPARATOR.$path : $path);
}
}
Create the scout.php
config file in app/config
folder with the following contents
<?php
return [
'driver' => env('SCOUT_DRIVER', 'pgsql'),
'prefix' => env('SCOUT_PREFIX', ''),
'queue' => false,
'pgsql' => [
'connection' => 'pgsql',
'maintain_index' => true,
'config' => 'english',
],
];
Register service providers:
// bootstrap/app.php
$app->register(Laravel\Scout\ScoutServiceProvider::class);
$app->configure('scout');
$app->register(ScoutEngines\Postgres\PostgresEngineServiceProvider::class);
Specify the database connection that should be used to access indexed documents in the Laravel Scout configuration file config/scout.php
:
// config/scout.php
...
'pgsql' => [
// Connection to use. See config/database.php
'connection' => env('DB_CONNECTION', 'pgsql'),
// You may want to update index documents directly in PostgreSQL (i.e. via triggers).
// In this case you can set this value to false.
'maintain_index' => true,
// You can explicitly specify what PostgreSQL text search config to use by scout.
// Use \dF in psql to see all available configurations in your database.
'config' => 'english',
// You may set the default querying method
// Possible values: plainquery, phrasequery, tsquery
// plainquery is used if this option is omitted.
'search_using' => 'tsquery'
],
...
Make sure that an appropriate default text search configuration is set globbaly (in postgresql.conf
), for a particular database (ALTER DATABASE ... SET default_text_search_config TO ...
) or alternatively set default_text_search_config
in each session.
To check the current value
SHOW default_text_search_config;
By default the engine expects that parsed documents (model data) are stored in the same table as the Model in a column searchable
of type tsvector
. You'd need to create this column and an index in your schema. You can choose between GIN
and GiST
indexes in PostgreSQL.
class CreatePostsTable extends Migration
{
public function up()
{
Schema::create('posts', function (Blueprint $table) {
$table->increments('id');
$table->text('title');
$table->text('content')->nullable();
$table->integer('user_id');
$table->timestamps();
});
DB::statement('ALTER TABLE posts ADD searchable tsvector NULL');
DB::statement('CREATE INDEX posts_searchable_index ON posts USING GIN (searchable)');
// Or alternatively
// DB::statement('CREATE INDEX posts_searchable_index ON posts USING GIST (searchable)');
}
public function down()
{
Schema::drop('posts');
}
}
In addition to Model's attributes you can bring other any other data to the index document. I.e. a list of Tags for a Post.
public function toSearchableArray()
{
return [
'title' => $this->title,
'content' => $this->content,
'author' => $this->user->name,
'tags' => $this->tags->pluck('tag')->implode(' '),
];
}
You may fine tune the engine behavior for a particular Model by implemeting searchableOptions()
in your Model.
class Post extends Model
{
use Searchable;
// ...
public function searchableOptions()
{
return [
// You may wish to change the default name of the column
// that holds parsed documents
'column' => 'indexable',
// You may want to store the index outside of the Model table
// In that case let the engine know by setting this parameter to true.
'external' => true,
// If you don't want scout to maintain the index for you
// You can turn it off either for a Model or globally
'maintain_index' => true,
// Ranking groups that will be assigned to fields
// when document is being parsed.
// Available groups: A, B, C and D.
'rank' => [
'fields' => [
'title' => 'A',
'content' => 'B',
'author' => 'D',
'tags' => 'C',
],
// Ranking weights for searches.
// [D-weight, C-weight, B-weight, A-weight].
// Default [0.1, 0.2, 0.4, 1.0].
'weights' => [0.1, 0.2, 0.4, 1.0],
// Ranking function [ts_rank | ts_rank_cd]. Default ts_rank.
'function' => 'ts_rank_cd',
// Normalization index. Default 0.
'normalization' => 32,
],
// You can explicitly specify a PostgreSQL text search configuration for the model.
// Use \dF in psql to see all available configurationsin your database.
'config' => 'simple',
];
}
}
...
If you decide to keep your Model's index outside of the Model's table you can let engine know that you want to push additional fields in the index table that you can then use to filter the result set by applying where()
with the Scout Builder
. In this case you'd need to implement searchableAdditionalArray()
on your Model. Of course the schema for the external table should include these additional columns.
public function searchableAdditionalArray()
{
return [
'user_id' => $this->user_id,
];
}
You may want to make your searchable column hidden so it's not standing in your way
protected $hidden = [
'searchable',
];
// plainto_tsquery()
$posts = App\Post::search('cat rat')
->usingPlainQuery()->get()
// phraseto_tsquery()
$posts = App\Post::search('cat rat')
->usingPhraseQuery()->get()
// to_tsquery()
$posts = App\Post::search('fat & (cat | rat)')
->usingTsQuery()->get()
// websearch_to_tsquery()
// uses web search syntax
$posts = App\Post::search('"sad cat" or "fat rat" -mouse')
->usingWebSearchQuery()->get()
// DIY using a callback
use ScoutEngines\Postgres\TsQuery\ToTsQuery;
$results = App\Post::search('fat & (cat | rat)', function ($builder, $config) {
return new ToTsQuery($builder->query, $config);
})->get();
Please see the official documentation on how to use Laravel Scout.
composer test
If you discover any security related issues, please email pmatseykanets@gmail.com instead of using the issue tracker.
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.