PHPackages                             aerynl/refinement - 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. [Framework](/categories/framework)
4. /
5. aerynl/refinement

ActiveLibrary[Framework](/categories/framework)

aerynl/refinement
=================

Easy refinements for use with Laravel

1.1.0(7y ago)0202MITPHP

Since Feb 21Pushed 6y ago3 watchersCompare

[ Source](https://github.com/aerynl/refinement)[ Packagist](https://packagist.org/packages/aerynl/refinement)[ Docs](http://github.com/aerynl/refinement)[ RSS](/packages/aerynl-refinement/feed)WikiDiscussions master Synced today

READMEChangelog (4)DependenciesVersions (2)Used By (0)

Refinement package
==================

[](#refinement-package)

Short description
-----------------

[](#short-description)

Easy refinements for use with Laravel. Contains functions for saving filters in Session, generating filter options and fetching filter results.

Quick start
-----------

[](#quick-start)

```
composer require aerynl/refinement
php artisan vendor:publish --provider="Aerynl\Refinement\RefinementServiceProvider"

```

Second command will create `\app\config\packages\aerynl\refinement\config.php` file, where you can specify table connections and filter names.

How to use
----------

[](#how-to-use)

If you want to save filters in session, run:

```
$refinements = array(
	'products' => array(
		'color_id' => array(12, 13, 14)
	);
);
Refinement::updateRefinements("products_filters", $refinements);

```

If you want to get filtered results, run:

```
$products_query = Refinement::getRefinedQuery("Product", "products_filters");
$products = $products_query->paginate(10);

```

If you want to get refinement options, run:

```
$options_scheme = array(
	'parent_table' => 'products', 'join_table' => 'colors', 'filter_column' => 'color_id', 'filter_value' => 'color_name'
);
$products_options = Refinement::getRefinedQuery("Product", $options_scheme, "products_filters");

```

What to write in config file
----------------------------

[](#what-to-write-in-config-file)

In config file you can specify table connections in `joins` array and filter names in `titles` array.

#### Table connections

[](#table-connections)

Sometimes we need to make joins to create the necessary queries.

Because it's hard to create proper queries from the inputted parameters the configuration below will be used to create the joins. **Be sure all the tables you are using for filtering have join configuration!**Note, this doesn't mean you should specify in join array tables, which are used to get options. For example, if you filter products by `product.color_id` and you have table `colors`, where all colors are kept, there is no need to add `colors` table to joins array. But if you always need to show only that products, which have `product_sale.active` = `false`, be sure that `product_sale` table is specified in config file.

Joins array has the following scheme:

```
'joins' => array(
        '$table1_name|$table2_name' => array(
            'left' => '$table1_name.$table1_column',
            'operand' => '=', // or whatever you want
            'right' => '$table2_name.$table2_column'
        ),
		...
     );

```

#### Titles of filters

[](#titles-of-filters)

Configure the name of your refinements here. If no name is entered the standard naming format will be used ([ucfirst](http://php.net/manual/ru/function.ucfirst.php))

Example:

```
'titles' => array(
    'products|color_id' => 'Product color',
	...
);

```

Refinement title translations
-----------------------------

[](#refinement-title-translations)

Create a file called refinements.php in `/app/lang/en`, there you'll be able to add translations for the titles you've added to the configuration.

Detailed information about functions
------------------------------------

[](#detailed-information-about-functions)

#### `Refinement::updateRefinements($session_name, $new_refinements)`

[](#refinementupdaterefinementssession_name-new_refinements)

This method is used to save filters in session. `$session_name` is the name of session, so you can use several filters sessions in one application. `$new_refinements` is a new filters array, that should be remembered. Keep the following scheme to have package work correctly:

```
$new_refinements = array(
	'$table_name1' => array(
		'$table_column1' => array(
			$value1, $value2, $value3
		),
		'$table_column2' => array(
			$value1, $value2, $value3
		),
		...
	),
	...
);

```

#### `Refinement::getRefinedQuery($main_model, [$session_name, $eager, $additional_wheres, $additional_joins, $refinements_array])`

[](#refinementgetrefinedquerymain_model-session_name-eager-additional_wheres-additional_joins-refinements_array)

This method is used to generate query for getting filtered results. Why doesn't it return filtered results? Sometimes you will need to do some operations with query before getting the results, for example groupBy, orderBy, paginate and others. So you can use this function in the following way:

```
$products_query = Refinement::getRefinedQuery("Product", "products_filters");
$products = $products_query->paginate(10);

```

Passed variables:

- `$main_model` - string main model name.
- `$session_name` - string session name.
- `$eager` - array of tables, which you want to eager load.
- `$additional_wheres` - array of additional where conditions, which need to be ran. For example `array("products.active is true", "products.deleted is null")`. Note, if your conditions use other tables, except of main one, you need to specify these tables in `$additional_joins` (and in config file).
- `$additional_joins` - array of additional tables, which are used in `$additional_wheres`. Note, these tables need to be configured in config file.
- `$refinements_array` - is used in case you need to get query with filters not from session, but from custome array. Should have the same format as `$new_refinements` in `updateRefinements` function. In this case session refinements are not used.

#### `Refinement::generateOptionsArray($main_model, [$options_scheme, $session_name, $eager, $additional_wheres, $additional_joins])`

[](#refinementgenerateoptionsarraymain_model-options_scheme-session_name-eager-additional_wheres-additional_joins)

This method is used for generating array of refinements options using passed scheme. It returns array of options with the following scheme:

```
$options_array = array(
	array(
		'column_name' => string $column_name, // e.g. 'color_id'.
		'parent_table' => string $parent_table // e.g. 'products'.
		'title' => string $category_title	// is taken from Config titles array
		'options' => array(
			$option_id => array(
				'name' => string $option_name,  // e.g. "White"
				'id' => mixed $option_id,		// not integer, but mixed in case you filter by enum field or something else.
				'count' => int $number_of_results,
				'checked' => bool $is_checked
			),
			...
		)
	),
	...
	);

```

`$column_name`, `$parent_table` and `$option_id` are used for creating $new\_refinements array for updateRefinements function. For example you can show options like checkboxes with `name="$parent_table[$column_name][]"` and `value="$option_id"`.

Passed variables: Note, first 5 variables should be the same as for `getRefinedQuery` function if you want to have actual $number\_of\_results.

- `$main_model` - string main model name.
- `$session_name` - string session name.
- `$eager` - array of tables, which you want to eager load.
- `$additional_wheres` - array of additional where conditions, which need to be ran. For example `array("products.active is true", "products.deleted is null")`. Note, if your conditions use other tables, except of main one, you need to specify these tables in `$additional_joins` (and in config file).
- `$additional_joins` - array of additional tables, which are used in `$additional_wheres`. Note, these tables need to be configured in config file.
- `$options_scheme` - scheme of options we want to select in the following format:

```
$options_scheme = array(
	array(
		'parent_table' => string $parent_table_name, - filtering is based on this table
		'filter_column' => string $parent_table_column - column of $parent_table. filtering is based on this column
		'join_table' => string $join_table_name, - table, which is joined to parent table and contains option names
		'filter_value' => string $join_table_column - column with option names
		'additional_wheres' => array of strings - additional where statements
	),
	...
);

```

e.g.

```
$options_scheme = array(
	'parent_table' => 'products', 'join_table' => 'colors', 'filter_column' => 'color_id', 'filter_value' => 'color_name', 'additional_wheres' => array("colors.deleted_at is null")
);

```

This means, that results are filtered by `products.color_id`. And color names you can see in `colors.color_name` column.

What will be done soon
----------------------

[](#what-will-be-done-soon)

- Laravel 5 supporting
- While I was writing this documentation, I had a great idea! We can avoid passing so many parameters each time by changing static methods to non-static.

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

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

Unknown

Total

1

Last Release

2689d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/fa95a51643d6a2a916dd0dfaaa3373816b95e155627b8c92572dff04557727c7?d=identicon)[aerynl](/maintainers/aerynl)

---

Top Contributors

[![kaylucas](https://avatars.githubusercontent.com/u/2276319?v=4)](https://github.com/kaylucas "kaylucas (25 commits)")[![lespavl](https://avatars.githubusercontent.com/u/1397340?v=4)](https://github.com/lespavl "lespavl (16 commits)")[![maxmaster82](https://avatars.githubusercontent.com/u/3645294?v=4)](https://github.com/maxmaster82 "maxmaster82 (11 commits)")[![aerynl](https://avatars.githubusercontent.com/u/11734601?v=4)](https://github.com/aerynl "aerynl (6 commits)")

---

Tags

laravelrefinement

### Embed Badge

![Health badge](/badges/aerynl-refinement/health.svg)

```
[![Health](https://phpackages.com/badges/aerynl-refinement/health.svg)](https://phpackages.com/packages/aerynl-refinement)
```

###  Alternatives

[hemp/presenter

Easy Model Presenters in Laravel

247616.4k1](/packages/hemp-presenter)[rahulalam31/laravel-abuse-ip

Block ip address of all spammer's around the world.

27235.6k](/packages/rahulalam31-laravel-abuse-ip)[glhd/linen

21441.7k](/packages/glhd-linen)[laravel-frontend-presets/black-dashboard

Laravel 11.x Front-end preset for black dashboard

8726.9k](/packages/laravel-frontend-presets-black-dashboard)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)