trail / search
Database search for trail
0.5.0
2026-11-16 22:02 UTC
Requires
- php: >=8.4
- ext-mbstring: *
- trail/db: ^0.5.0
- trail/framework: ^0.5.0
Requires (Dev)
None
Suggests
- trail/twig: `highlight` and `excerpt` filters
Provides
None
Conflicts
None
Replaces
None
README
Search addon for trail
install
composer require trail/search
trail/trail db::migrate
guidebook
All words get converted to lowercase, any accents dropped, and some splits. You can add your own weights
use Trail\Search\Guidebook\Guidebook;
$guidebook->put('card', $card->id, [
[$card->title, 10],
[$card->description, 1],
]);
$guidebook->put('page', $page->id, [[$page->title, 10]], scope: 'ja'); // sites, stuff, etc
$guidebook->forget('card', $card->id);
search
use Trail\Search\Tracks\Tracks;
[$where, $params] = $tracks->where('card', 'c.id', $query);
$score = $tracks->score('card', 'c.id', $query);
$cards = $database->all("
select c.* from cards c
where c.board_id = ? and {$where}
order by {$score} desc
limit 20
", [$boardId, ...$params]);
Or just the ids
$tracks->find('card', $query, limit: 20, offset: 0);
Use -word to exclude things, or match: 'any' accept any
$tracks->find('card', 'plan -backup');
$tracks->where('card', 'c.id', 'meeting notes', match: 'any');
did you mean?!
$signpost->for('card', 'plannning'); // 'planning' or null
// only what they're allowed to see
$signpost->for('card', $query, visible: ['select id from cards where board_id = ?', [$boardId]]);
highlights
$lantern->highlight($card->title, $query);
$lantern->excerpt($card->description, $query, 160);
Twig::extension(SearchTwig::class);
{{ card.title|highlight(query) }}
{{ card.description|excerpt(query) }}
rebuild
Guide the guidebook and it can rebuild
final readonly class CardWords implements Source
{
public function __construct(private Connection $database) {}
public function kind(): string
{
return 'card';
}
public function records(): iterable
{
foreach ($this->database->all('select * from cards') as $card) {
yield new Marker($card->id, [[$card->title, 10], [$card->description, 1]]);
}
}
}
Search::source(CardWords::class);
trail/trail search::rebuild
trail/trail search::rebuild card
config
Lives in search section of app.php
'search' => [
'terms' => 8, // max words per search
'shortest' => 2, // shorter skipped
'longest' => 64, // longer trimmed, 64 max
'exactBonus' => 2, // exact vs start of
'match' => 'all', // any
'suggest' => ['shortest' => 3, 'candidates' => 300],
'mark' => ['tag' => 'mark', 'class' => null],
],
customise
You can bind a Chop to customise how stuff works. And Kindling for stops, plurals, synonyms, etc
final readonly class StopWords implements Chop
{
private const array STOP = ['the' => true, 'and' => true];
public function __construct(private Kindling $kindling) {}
public function words(string $text): array
{
return array_diff_key($this->kindling->words($text), self::STOP);
}
public function terms(string $query): array
{
return array_values(array_filter($this->kindling->terms($query), static fn (string $term): bool => !isset(self::STOP[$term])));
}
}
// your addons register()
$box->bind(Chop::class, StopWords::class);