Download the PHP package laragear/refine without Composer
On this page you can find all versions of the php package laragear/refine. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download laragear/refine
More information about laragear/refine
Files in laragear/refine
Package refine
Short Description Filter a database query using the request query keys and matching methods.
License MIT
Informations about the package refine
Refiner
Filter a database query using the request query keys and matching methods.
Become a sponsor
Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word on social media!.
Requirements
- Laravel 11 or later.
Installation
Require this package into your project using Composer:
Usage
This package solves the problem of refining a database query using the URL parameters by moving that logic out of the controller.
For example, imagine you want to show all the Posts made by a given Author ID. Normally, you would check that on the controller and modify the query inside.
While this looks inoffensive for a couple of URL parameters, it will add up as more refinements are needed: published at a given time, with a given set of tags, ordering by a given column, etc. Eventually it will clutter your controller action.
Instead, Laragear Refine moves that logic to its own "Refiner" object, which is handled by only issuing the refiner class name to the refineBy()
method of the query builder.
The magic is simple: each refiner method will be executed as long the corresponding URL parameter key is present in the incoming request. Keys are automatically normalized to camelCase
to match the method, so the author_id
key will execute authorId()
with its value.
Creating a Refiner
Call the make:refiner
with the name of the Refiner you want to create.
You will receive the refiner in the app\Http\Refiners
directory.
As you can see, apart from the constructor, the class is empty. The next step is to define methods to match the request keys.
Defining methods
You may define the methods you want to be executed when a URL parameter key is present by simple creating these as public, using their corresponding camelCase
key.
All methods you set in the Refiner class receive the Query Builder instance, the value from the request, and the Illuminate\Http\Request
instance itself. Inside each method, you're free to modify the Query Builder as you see fit, or even call authorization gates or check the user permissions.
Only some keys
On rare occasions, you may have a method you don't want to be executed as part of the refinement procedure, especially if your Refiner is extending another Refiner. In that case, you may instruct which URL parameters keys should be used to match their respective methods with the getKeys()
method.
Alternatively, if you're using a FormRequest
, you can always return the keys of the validated data.
Obligatory keys
Sometimes you will want to run a method even if the key is not set in the URL parameters. For that, use the getObligatoryKeys()
method to return the keys (and methods) that should always run.
For example, if we want to run the orderBy()
method regardless if there is the order_by
URL parameter, we only need to return that key.
Then, the method should be able to receive a null
value when the URL parameter is not set.
Dependency Injection
The Refiner class is always resolved using the application container. You can type-hint any dependency in the class constructor and use it later on the matching methods.
Validation
You may also include validation logic into your Refiner by implementing the ValidateRefiner
interface. From there, you should set your validation rules, and optionally your messages and custom attributes if you need to.
This is great if you expect a key to always be required in the query, as the validationRules()
is an excellent place to do it.
[!NOTE]
Validation rules will run verbatim over the Request Query, not the request input.
Applying a Refiner
In your Builder instance, simply call refineBy()
with the name of the Refiner class (or its alias if you registered it on the application container) to apply to the query.
The refineBy()
is a macro registered to the Eloquent Builder and the base Query Builder, and you can use it even after your own custom refinements.
Custom keys
You can override the keys to look for on the Request at runtime by issuing the keys as second argument. These will replace the custom keys you have set in the class.
Model Refiner
You may use the included ModelRefiner
to quickly create a refiner for a database query over a model. The Model Refiner simplifies automatically the following URL parameters:
query
to search by both primary key or text contained in predetermined columns.only[]
to only retrieve certain of columns.has[]
to retrieve items that have at least one related model.has_not[]
to retrieve items that doesn't have a related model.with[]
to retrieve items including a relation or nested relation.with_count[]
to include the count of the given relations.with_sum[]
to include the count of the given relation column.trashed
to include trashed items in the query.order_by|order_by_desc
to determine which column to use for ordering.limit|per_page
to limit the number of items retrieved.
Creating a Model Refiner
Simply call the make:refiner
with the --model
option.
You will receive a refiner extending the base ModelRefiner
. Here you should set the relations, columns, sums, and order the refiner should use to validate the URL parameters values. This way you can have control on which columns or relations are permitted to be set in the query.
As with a normal refiner, you may also override the validation keys and/or the keys to check in the request, and even how each query key should be refined.
[!TIP]
Even if you validate relations using
snake_case
, when building the query for relations, these will be automatically transformed intocamelCase
, even if these are separated bydot.notation
. No need to change case.
Full text search
By default, when receiving a string to search as "query", the Model Refiner will use an ILIKE
operator to search inside one or many columns. This approach will work on all SQL engines.
Alternatively, you may use PostgreSQL or MySQL full-text search capabilities by setting $fullTextSearch
as true
in your Model Refiner.
Sum relations
The ModelRefiner
supports summing relations columns using the relation name and the column separated by a hyphen. You may want to set an array of relations and possible columns to sum by returning them in the getSumRelations()
method.
The above will make calls to the userComments()
relation of the queried model.
Laravel Octane compatibility
- There are no singletons using a stale application instance.
- There are no singletons using a stale config instance.
- There are no singletons using a stale request instance.
- A static property being written is the cache of Refiner methods which grows by every unique Refiner that runs.
- A static property being written is the cache of Abstract Refiner methods which is only written once.
The cached Refiner methods shouldn't grow uncontrollably, unless you have dozens of Refiner classes being called multiple times. In any case, you can always flush the cached refiner methods using the RefineQuery::flushCachedRefinerMethods()
.
There should be no problems using this package with Laravel Octane.
Security
If you discover any security related issues, please use the online form.
License
This specific package version is licensed under the terms of the MIT License, at time of publishing.
Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2025 Laravel LLC.
All versions of refine with dependencies
illuminate/http Version 11.*|12.*
illuminate/database Version 11.*|12.*
illuminate/console Version 11.*|12.*