PHPackages zarbinco/laravel-persian-search - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. zarbinco/laravel-persian-search ActiveLibrary[Database & ORM](/categories/database) zarbinco/laravel-persian-search =============================== Persian-aware document search, multilingual typo correction, query expansion, indexing, and relevance tools for Laravel. v1.1.0(3w ago)15MITPHPPHP ^8.2CI passing Since Jul 24Pushed 1mo agoCompare [ Source](https://github.com/zarbinco/laravel-persian-search)[ Packagist](https://packagist.org/packages/zarbinco/laravel-persian-search)[ Docs](https://github.com/zarbinco/laravel-persian-search)[ RSS](/packages/zarbinco-laravel-persian-search/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (14)Versions (3)Used By (0) Laravel Persian Search ====================== [](#laravel-persian-search) Laravel Persian Search provides Persian-aware indexing, database search, relevance scoring, query expansion, configurable synonyms, and wrong-keyboard typing correction for Laravel applications. It is powered by `zarbinco/laravel-persian-core` for normalization and tokenization. Features -------- [](#features) - Delegates Persian search normalization and tokenization to `laravel-persian-core` - Searchable Eloquent model declarations - In-memory normalized search documents - Database-backed search index - Manual indexing and deletion APIs - Automatic indexing on save, delete, and restore - Reindex and flush console commands - Portable database search driver - Relevance-ranked Eloquent model results - Result objects with scores, matched tokens, candidate source, and matched query - Query candidate expansion - Configurable synonyms - Wrong-keyboard typing correction for English-keyboard input intended as Persian Requirements ------------ [](#requirements) - PHP `^8.2` - Laravel components `^11.0`, `^12.0`, or `^13.0` - `zarbinco/laravel-persian-core` Installation ------------ [](#installation) Install the package with Composer: ``` composer require zarbinco/laravel-persian-search ``` The package depends on `zarbinco/laravel-persian-core`, which Composer installs as a production dependency. Laravel package auto-discovery registers the service provider and optional facade alias. Configuration ------------- [](#configuration) Publish the configuration and migration files with the install command: ``` php artisan persian-search:install php artisan migrate ``` You may also publish them manually: ``` php artisan vendor:publish --tag=persian-search-config php artisan vendor:publish --tag=persian-search-migrations php artisan migrate ``` The default driver is `database`. Search limits, candidate loading, indexing behavior, query expansion, synonyms, keyboard correction, and ranking weights are configured in `config/persian-search.php`. Defining Searchable Models -------------------------- [](#defining-searchable-models) Models describe their searchable content by using `HasPersianSearch` and returning weighted searchable fields: ``` use Illuminate\Database\Eloquent\Model; use Zarbinco\PersianSearch\Eloquent\HasPersianSearch; final class Product extends Model { use HasPersianSearch; public function persianSearchableFields(): array { return [ 'name' => 10, 'brand.name' => 5, 'description' => 1, ]; } } ``` Field values may come from model attributes or loaded relation paths such as `brand.name`. Field weights are stored and used by the database ranker. Manual Indexing --------------- [](#manual-indexing) Persist a normalized search document manually: ``` use Zarbinco\PersianSearch\Facades\PersianSearch; PersianSearch::index($product); $product->savePersianSearchDocument(); ``` Remove a model from the index: ``` PersianSearch::deleteFromIndex($product); $product->deletePersianSearchDocument(); ``` Automatic Indexing ------------------ [](#automatic-indexing) When `persian-search.index.sync_on_save` is enabled, models using `HasPersianSearch` are indexed after save. When `persian-search.index.delete_on_model_delete` is enabled, deleted models are removed from the index. Soft-deleted models are removed unless `include_soft_deleted` is enabled. Restored models are indexed again when automatic sync is enabled. Reindexing ---------- [](#reindexing) Rebuild search documents for a model: ``` php artisan persian-search:reindex "App\Models\Product" --fresh ``` The `--fresh` option removes existing indexed documents for that model before reindexing. Flushing -------- [](#flushing) Flush one searchable model type: ``` php artisan persian-search:flush "App\Models\Product" ``` Flush all search documents: ``` php artisan persian-search:flush --force ``` Without `--force`, flushing all documents asks for confirmation. Searching --------- [](#searching) Search indexed models through the facade: ``` use Zarbinco\PersianSearch\Facades\PersianSearch; $products = PersianSearch::search('كیك شکلاتي') ->for(App\Models\Product::class) ->get(); ``` Search through the model convenience API: ``` $products = App\Models\Product::persianSearch('كیك شکلاتي')->get(); ``` Use locale filtering when indexed documents include locales: ``` $products = PersianSearch::search('كیك') ->for(App\Models\Product::class) ->locale('fa') ->get(); ``` Disable query expansion for a single search when exact normalized query behavior is needed: ``` $products = App\Models\Product::persianSearch('كیك شکلاتي') ->withoutExpansion() ->get(); ``` Result Objects -------------- [](#result-objects) Fetch result objects when you need scores and match metadata: ``` $results = PersianSearch::search('كیك شکلاتي') ->for(App\Models\Product::class) ->results(); foreach ($results->items() as $result) { $result->model; $result->score; $result->matchedTokens; $result->candidateSource; $result->matchedQuery; } ``` Query Expansion --------------- [](#query-expansion) Search queries are expanded into candidates at search time. The original normalized query is always kept as the first candidate, and additional candidates can come from wrong-keyboard correction and configured synonyms. Query candidates are not stored in the index. Indexed document titles, content, fields, and tokens remain normalized model data only. Inspect candidates through the facade: ``` $candidates = PersianSearch::expand(';dt'); ``` Each candidate includes its source, original candidate text, normalized text, tokens, and boost. Synonyms -------- [](#synonyms) Synonym expansion is configurable and disabled by default: ``` 'synonyms' => [ 'enabled' => true, 'bidirectional' => true, 'max_candidates' => 20, 'boost' => 0.85, 'map' => [ 'گوشی' => ['موبایل', 'تلفن همراه'], ], ], ``` With that configuration, this query can match indexed content such as `گوشی سامسونگ`: ``` $products = Product::persianSearch('موبایل سامسونگ')->get(); ``` Synonym keys and values are normalized and tokenized through `SearchNormalizer`, which delegates to `laravel-persian-core`. Wrong-Keyboard Typing Correction -------------------------------- [](#wrong-keyboard-typing-correction) Wrong-keyboard correction handles English-keyboard input intended as Persian: ``` $products = Product::persianSearch(';dt')->get(); ``` The query above can match indexed content such as `کیف`. This happens only at query time. It does not mutate stored index content, and it is not part of `laravel-persian-core` normalization. Wrong-keyboard typing correction belongs to `laravel-persian-search` as query candidate expansion. Persian-to-English correction is not enabled by default. Relevance Scoring ----------------- [](#relevance-scoring) The database ranker scores persisted documents using: - Exact normalized phrase matches in title and content - All query tokens present in the document - Individual token matches - Title boosts - Stored field weights - Query candidate boosts The database driver scores each indexed document against query candidates and uses the best boosted score for ordering. The original query receives the strongest default boost, keyboard-corrected candidates receive a slightly lower boost, and synonym candidates receive configurable lower boosts. Console Commands ---------------- [](#console-commands) ``` php artisan persian-search:install php artisan persian-search:reindex "App\Models\Product" --fresh php artisan persian-search:flush "App\Models\Product" php artisan persian-search:flush --force ``` Boundaries ---------- [](#boundaries) This package uses portable database search by default. It is not a full-text engine. `laravel-persian-core` owns Persian text normalization, digit conversion, punctuation cleanup, ZWNJ handling, and tokenization. `laravel-persian-search` owns searchable model declarations, indexing, search execution, relevance scoring, and query intent features such as synonyms and wrong-keyboard correction. This package does not currently provide Scout, Meilisearch, or Elasticsearch adapters. It does not perform fuzzy typo correction, stemming, or transliteration. Planned Capabilities -------------------- [](#planned-capabilities) - Scout adapter - Meilisearch and Elasticsearch adapters - Search analytics - Suggestion engine - More advanced ranking strategies Release Notes ------------- [](#release-notes) See [CHANGELOG.md](CHANGELOG.md). Testing ------- [](#testing) ``` composer test composer analyse composer format -- --test ``` ### Health Score 40 — FairBetter than 86% of packages Maintenance92 Actively maintained with recent releases Popularity7 Limited adoption so far Community8 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 83.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 2 Last Release 25d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b3f772fb52747f8a5886d060e6da693a7aef6952200c2227d49c68ff4a1b4bfe?d=identicon)[zarbinco](/maintainers/zarbinco) --- Top Contributors [![mrezdev](https://avatars.githubusercontent.com/u/6697319?v=4)](https://github.com/mrezdev "mrezdev (5 commits)")[![ahmadpour1990](https://avatars.githubusercontent.com/u/246503754?v=4)](https://github.com/ahmadpour1990 "ahmadpour1990 (1 commits)") --- Tags searchlaraveleloquentlaravel-packagedid you meanindexingiranpersianfarsiword segmentationtypo-tolerancespelling correctionfarsi-searchpersian-searchquery-expansionphonetic-searchcontextual-searchreal-word-correction ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/zarbinco-laravel-persian-search/health.svg) ``` [![Health](https://phpackages.com/badges/zarbinco-laravel-persian-search/health.svg)](https://phpackages.com/packages/zarbinco-laravel-persian-search) ``` ### Alternatives [laravel/scout Laravel Scout provides a driver based solution to searching your Eloquent models. 1.7k57.2M684](/packages/laravel-scout)[laravel/ai The official AI SDK for Laravel. 1.1k4.6M331](/packages/laravel-ai)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k16.3M155](/packages/laravel-pulse)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9922.4M147](/packages/roots-acorn)[propaganistas/laravel-disposable-email Disposable email validator 6023.2M7](/packages/propaganistas-laravel-disposable-email)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)