Skip to content

Define fields

Declare the filterable fields of a model with searchChips(), or let the package discover them.

Updated

A model has two ways to say which fields are filterable. You declare them, or the package discovers them. Declare them for any model that users search.

Declare fields

Add the HasSearchChips trait and a searchChips(ChipSchema $chips) method. The model then exposes exactly the fields you list. No other field is reachable. The package runs no table query for a declared model.

use Illuminate\Database\Eloquent\Model;
use Meirdick\SearchChips\HasSearchChips;
use Meirdick\SearchChips\Schema\ChipSchema;

class Post extends Model
{
    use HasSearchChips;

    public function searchChips(ChipSchema $chips): void
    {
        $chips->text('title')->searchable();
        $chips->enum('type', PostType::class)->synonyms(['movie' => 'video', 'show' => 'podcast']);
        $chips->number('views')->aliases('plays')->sortable();
        $chips->boolean('is_featured')->label('Featured')->aliases('featured');
        $chips->datetime('published_at')->label('Published')->sortable();
        $chips->relation('author', 'name');
    }
}

Field types

Method Kind Notes
text($column) text Free text.
number($column) number Integer or decimal.
date($column) date A date.
datetime($column) datetime A date and time.
boolean($column) boolean Yes or no.
enum($column, $values) enum $values is a backed enum class, a list of values, or a value => label map.
relation($relation, $column = 'name') text Filters by a column of a related model. The field name is relation.column. The relation word is an alias. The related column is also part of the keyword search. Use ->searchable(false) to turn that off.

A relation() field needs a relation method with that name on the model. If the method does not exist, the package drops the field.

Field options

Each method returns a ChipField. Chain these options on it.

Option Use
label(string $label) The name that chips and the panel show. The default is the column name in words.
aliases(string ...$aliases) Words in a sentence that mean this field, for example ->aliases('plays', 'view count').
values(string|array $values) The allowed values. enum() calls this for you.
synonyms(array $synonyms) Other words for a value, as word => value. The package also reads the plural of each word.
unit(string $unit, ?float $scale = null) A unit and a scale. ->unit('percent', scale: 0.01) turns 8% into 0.08.
searchable(bool $searchable = true) Keyword text searches this text field.
sortable(bool $sortable = true) Words such as latest or most viewed can sort by this field.
onlyWhen(array $conditions) A filter on this field only selects rows that meet the conditions. See Security.

Discovery

If the model has no searchChips() method, the package discovers its fields.

  • It reads the kind of each column from the model casts. For a column with no cast, it uses the column type.
  • It skips hidden attributes, columns that end in _id, the soft-delete column, columns with a cast to array, json or encrypted, and columns whose name matches password, passwd, token, secret, remember, api_key, _hash, salt, private or internal.
  • It adds a relation.name field for each public relation method that has a return type. The name column is the first of name, title, label, username and slug that the related table has.
  • Date fields are sortable. Text fields named title, name, body, content, description, summary, subject, caption or text are searchable. If none matches, the first text column is searchable.

Discovery needs a database connection. Add #[Filterable] and #[Unfilterable] attributes to the model class to change what it finds.

use Meirdick\SearchChips\Attributes\Filterable;
use Meirdick\SearchChips\Attributes\Unfilterable;

#[Filterable('views', aliases: ['view count', 'plays'], orderable: true)]
#[Filterable('engagement_rate', label: 'Engagement', unit: 'percent', scale: 0.01)]
#[Unfilterable('internal_note')]
class Post extends Model {}

#[Filterable] takes field, label, unit, scale, aliases, values, searchable and orderable. #[Unfilterable] on the class with no argument keeps the whole model out of discovery. On a relation method, it hides that relation. The attributes apply to discovery only. They do not change a model that declares searchChips().

Discovery can also sample values. See discovery.sample_values in Configuration and Security.

What discovery sets with no field list:

  • A flag column gets a short label: is_featured shows as “Featured”. A date column does too: published_at shows as “Published”.
  • A number column can be sorted, so “most viewed” works.
  • A column with a name that ends in _rate, _ratio, _percent, _percentage or _pct, and with no value above 1, is read as a percent. “Above 5%” becomes 0.05.
  • The keyword search reads the first text column and the name column of each relation, three relations at most. A bare name such as “hopper” finds the posts of that author.
  • An AI engine is not asked about the primary key. It is not asked about created_at and updated_at when the model has another date column. The rules still read id: 42.
  • With discovery.sample_values on, a text column with 2 to 8 different values gets a value list. A chip for a value that is not in the list is dropped.

Discovery cannot know other words for a value. With the system-one engine, a Clef decision model maps a common word such as “movies” to the value video. See Other words for a value. For a word that is specific to your app, add a synonym in searchChips().

For a model that users search, declare the fields. Discovery can expose a column that you did not intend.

The search-chips:schema command with --stub prints a searchChips() method from the discovered schema. Paste it into the model and remove what you do not need.

php artisan search-chips:schema posts --stub

The model must be registered first. See Register models. Without --stub, the command prints a table of the fields. With --json, it prints JSON.

Next steps

Type to search…

↑↓ navigate↵ selectEsc close