Searchable Laravel Package

Getting Started

• Install with Composer: composer require fab2s/searchable.
• Check PHP compatibility first: v1.1.0 bumps the package requirement to PHP 8.5. Confirm php -v, CI images, and production runtime before upgrading.
• Look first at the package README and tests for the exact trait namespace, searchable-column configuration, and search scope signature.
• Add the trait to the Eloquent model you want to search and declare the columns that should be searchable. Typical shape:

use Fab2s\Searchable\Searchable;

class Post extends Model
{
    use Searchable;

    protected $searchable = [
        'title',
        'body',
    ];
}

• First practical use case: an admin list filter.

$posts = Post::query()
    ->search($request->string('q'))
    ->latest()
    ->paginate(25)
    ->withQueryString();

• Before relying on it, inspect the generated SQL with ->toSql() and ->getBindings() to confirm how terms are matched and escaped.

Implementation Patterns

• Keep search usage behind an app-level query scope or dedicated query class so controllers stay thin and the package can be replaced later without touching every endpoint.
• Chain the search scope with normal Eloquent scopes:

Post::query()
    ->search($term)
    ->published()
    ->with('author')
    ->paginate(25);

• Validate and normalize search input in a FormRequest: trim, enforce minimum/maximum length, and reject empty searches if an empty term would return all records.
• Use explicit searchable column lists. Do not make every column searchable by default; exclude sensitive fields and large text columns unless needed.
• For large tables, treat the package as a filtering convenience rather than a full search engine. Add indexes for commonly searched columns and consider database full-text search or an external engine when result quality and performance matter.
• Use pagination with withQueryString() so search terms survive page navigation.
• For multi-model search, put the orchestration in an application service/action and call each model’s search scope separately, then merge or present results in a predictable way.
• Test searches as feature tests against the same database engine used in production. SQLite, MySQL, and PostgreSQL differ in collation, case sensitivity, and LIKE behavior.
• When upgrading to v1.1.0, treat it primarily as a platform compatibility change: the release notes only mention the PHP 8.5 bump, so re-run search tests and verify Composer resolves the intended package version across local, CI, and production.

Gotchas and Tips

• v1.1.0 requires PHP 8.5. This is effectively a breaking platform change despite the minor version. If your app or hosting is not on PHP 8.5, pin to the previous compatible release range or delay the upgrade. Ensure composer.lock, CI images, and deployment runtimes all agree.
• Confirm how user input containing % and _ is handled. If the package does not escape LIKE wildcards, searches may behave unexpectedly or become expensive. Escape them or constrain input.
• Leading-wildcard searches such as %term% usually prevent normal index usage. Prefer prefix searches where possible, or move to full-text search for large datasets.
• Empty or very short terms may return all rows or no rows depending on package behavior and your guards. Handle this explicitly in the request/controller.
• Case sensitivity and accent matching depend on database collation. A search that works locally on SQLite may behave differently on MySQL or PostgreSQL.
• Do not assume relations are searched automatically unless the README documents it. Use whereHas, joins, or separate model searches deliberately.
• Debug slow or surprising searches with toSql(), getBindings(), and query logging. Check whether the final query still uses expected indexes.
• Keep the package integration isolated behind a model scope or application search class. That gives you a clean extension point for custom ranking, filters, or replacement with a dedicated search service later.