Download the PHP package lorisleiva/laravel-search-string without Composer

🔍 Laravel Search String

Generates database queries based on one unique string using a simple and customizable syntax.

Introduction

Laravel Search String provides a simple solution for scoping your database queries using a human readable and customizable syntax. It will transform a simple string into a powerful query builder.

For example, the following search string will fetch the latest blog articles that are either not published or titled "My blog article".

This next example will search for the term "John" on the customer and description columns whilst making sure the invoices are either paid or archived.

You can also query for the existence of related records, for example, articles published in 2020, which have more than 100 comments that are either not spam or written by John.

As you can see, not only it provides a convenient way to communicate with your Laravel API (instead of allowing dozens of query fields), it also can be presented to your users as a tool to explore their data.

Installation

Basic usage

Add the SearchString trait to your models and configure the columns that should be used within your search string.

Note that you can define these in customise the behaviour of each column.

That's it! Now you can create a database query using the search string syntax.

The search string syntax

Note that the spaces between operators don't matter.

Exact matches

Comparisons

Lists

Dates

The column must either be cast as a date or explicitly marked as a date in the column options.

Booleans

The column must either be cast as a boolean or explicitly marked as a boolean in the column options.

Alternatively, if the column is marked as a date, it will automatically be marked as a boolean using is null and is not null.

Negations

Null values

The term NULL is case sensitive.

Searchable

At least one column must be defined as searchable.

The queried term must not match a boolean column, otherwise it will be handled as a boolean query.

And/Or

Relationships

The column must be explicitly defined as a relationship and the model associated with this relationship must also use the SearchString trait.

When making a nested query within a relationship, Laravel Search String will use the column definition of the related model.

In the following examples, comments is a HasMany relationship and author is a nested BelongsTo relationship within the Comment model.

Note that all these expressions delegate to the has query method. Therefore, it works out-of-the-box with the following relationship types: HasOne, HasMany, HasOneThrough, HasManyThrough, BelongsTo, BelongsToMany, MorphOne, MorphMany and MorphToMany.

The only relationship type currently not supported is MorphTo since Laravel Search String needs an explicit related model to use withing nested queries.

Special keywords

Note that these keywords can be customised.

Configuring columns

Column aliases

If you want a column to be queried using a different name, you can define it as a key/value pair where the key is the database column name and the value is the alias you wish to use.

You can also provide a regex pattern for a more flexible alias definition.

Column options

You can configure a column even further by assigning it an array of options.

Key

The key option is what we've been configuring so far, i.e. the alias of the column. It can be either a regex pattern (therefore allowing multiple matches) or a regular string for an exact match.

Date

If a column is marked as a date, the value of the query will be parsed using Carbon whilst keeping the level of precision given by the user. For example, if the created_at column is marked as a date:

By default any column that is cast as a date (using Laravel properties), will be marked as a date for LaravelSearchString. You can force a column to not be marked as a date by assigning date to false.

Boolean

If a column is marked as a boolean, it can be used with no operator or value. For example, if the paid column is marked as a boolean:

If a column is marked as both boolean and date, it will be compared to null when used as a boolean. For example, if the published_at column is marked as boolean and date and uses the published alias:

By default any column that is cast as a boolean or as a date (using Laravel properties), will be marked as a boolean. You can force a column to not be marked as a boolean by assigning boolean to false.

Searchable

If a column is marked as searchable, it will be used to match search queries, i.e. terms that are alone but are not booleans like Apple Banana or "John Doe".

For example if both columns title and description are marked as searchable:

If no searchable columns are provided, such terms or strings will be ignored.

Relationship

If a column is marked as a relationship, it will be used to query relationships.

The column name must match a valid relationship method on the model but, as usual, aliases can be created using the key option.

The model associated with that relationship method must also use the SearchString trait in order to nest relationship queries.

For example, say you have an Article Model and you want to query its related comments. Then, there must be a valid comments relationship method and the Comment model must itself use the SearchString trait.

Note that, since Laravel Search String is simply delegating to the $builder->has(...) method, you can provide any fancy relationship method you want and the constraints will be kept. For example:

Configuring special keywords

You can customise the name of a keyword by defining a key/value pair within the $searchStringKeywords property.

Similarly to column values you can provide an array to define a custom key of the keyword. Note that the date, boolean, searchable and relationship options are not applicable for keywords.

Other places to configure

As we've seen so far, you can configure your columns and special keywords using the searchStringColumns and searchStringKeywords properties on your model.

You can also override the getSearchStringOptions method on your model which defaults to:

If you'd rather not define any of these configurations on the model itself, you can define them directly on the config/search-string.php file like this:

When resolving the options for a particular model, LaravelSearchString will merge those configurations in the following order:

1. First using the configurations defined on the model
2. Then using the config file at the key matching the model class
3. Then using the config file at the default key
4. Finally using some fallback configurations

Configuring case insensitive searches

When using databases like PostgreSql, you can override the default behavior of case sensitive searches by setting case_insensitive to true in your options amongst columns and keywords. For example, in the config/search-string.php

When set to true, it will lowercase both the column and the value before comparing them using the like operator.

Error handling

The provided search string can be invalid for numerous reasons.

• It does not comply to the search string syntax
• It tries to query an inexisting column or column alias
• It provides invalid values to special keywords like limit
• Etc.

Any of those errors will throw an InvalidSearchStringException.

However you can choose whether you want these exceptions to bubble up to the Laravel exception handler or whether you want them to fail silently. For that, you need to choose a fail strategy on your config/search-string.php configuration file: