├── CHANGELOG.md
├── LICENSE.md
├── README.md
├── composer.json
├── config
└── facet-filter.php
├── database
└── migrations
│ └── create_facetrows_table.php
├── demo.gif
└── src
├── Builders
└── FacetQueryBuilder.php
├── Collections
└── FacettableCollection.php
├── Facades
└── FacetFilter.php
├── FacetFilter.php
├── FacetFilterServiceProvider.php
├── Indexer.php
├── Models
├── Facet.php
└── FacetRow.php
└── Traits
├── Facettable.php
└── HasFacetCache.php
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | All notable changes will be documented in this file.
4 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) mgussekloo
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in
13 | all copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 | THE SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Laravel Facet Filter
2 |
3 | This package provides simple facet filtering (sometimes called Faceted Search or Faceted Navigation) in Laravel projects. It helps narrow down query results based on the attributes of your models.
4 |
5 | - Free, no dependencies
6 | - Easy to use in any project
7 | - Easy to customize
8 | - There's a [demo project](https://github.com/mgussekloo/Facet-Demo) to get you started
9 |
10 | 
11 |
12 | ### Contributing
13 |
14 | Please contribute to this package, either by creating a pull request or reporting an issue.
15 |
16 | ### Installation
17 |
18 | This package can be installed through [Composer](https://packagist.org/packages/mgussekloo/laravel-facet-filter).
19 |
20 | ``` bash
21 | composer require mgussekloo/laravel-facet-filter
22 | ```
23 |
24 | ## Prepare your project
25 |
26 | ### Update your models
27 |
28 | Add a Facettable trait and a facetDefinitions() method to models that should support facet filtering.
29 |
30 | ``` php
31 | use Illuminate\Database\Eloquent\Factories\HasFactory;
32 | use Illuminate\Database\Eloquent\Model;
33 |
34 | use Mgussekloo\FacetFilter\Traits\Facettable;
35 |
36 | class Product extends Model
37 | {
38 | use HasFactory;
39 | use Facettable;
40 |
41 | public static function facetDefinitions()
42 | {
43 | // Return an array of definitions
44 | return [
45 | [
46 | 'title' => 'Main color', // The title will be used for the parameter.
47 | 'fieldname' => 'color' // Model property from which to get the values.
48 | ],
49 | [
50 | 'title' => 'Sizes',
51 | 'fieldname' => 'sizes.name' // Use dot notation to get the value from related models.
52 | ]
53 | ];
54 | }
55 | }
56 |
57 |
58 | ```
59 |
60 | ### Publish and run the migrations
61 |
62 | For larger datasets you must build an index of all facets beforehand. If you're absolutely certain you don't need an index, skip to [filtering collections](#filtering-collections).
63 |
64 | ``` bash
65 | php artisan vendor:publish --tag="facet-filter-migrations"
66 | php artisan migrate
67 | ```
68 |
69 | ### Build the index
70 |
71 | Now you can start building the index. There's a simple Indexer included, you just need to configure it to run once, periodically or whenever a relevant part of your data changes.
72 |
73 | ``` php
74 | use Mgussekloo\FacetFilter\Indexer;
75 |
76 | $products = Product::with(['sizes'])->get(); // get some products
77 |
78 | $indexer = new Indexer();
79 |
80 | $indexer->resetIndex(); // clear the entire index or...
81 | $indexer->resetRows($products); // clear only the models that you know have changed
82 |
83 | $indexer->buildIndex($products); // process the models
84 | ```
85 |
86 | ## Get results
87 |
88 | ### Apply the facet filter to a query
89 |
90 | ``` php
91 | $filter = request()->all(); // use the request parameters
92 | $filter = ['main-color' => ['green']]; // (or provide your own array)
93 |
94 | $products = Product::facetFilter($filter)->get();
95 | ```
96 |
97 | ## Build the frontend
98 |
99 | ``` php
100 | $facets = Product::getFacets();
101 |
102 | /* You can filter and sort like any regular Laravel collection. */
103 | $singleFacet = $facets->firstWhere('fieldname', 'color');
104 |
105 | /* Find out stuff about the facet. */
106 | $paramName = $singleFacet->getParamName(); // "main-color"
107 | $options = $singleFacet->getOptions();
108 |
109 | /*
110 | Options look like this:
111 | (object)[
112 | 'value' => 'Red',
113 | 'selected' => false,
114 | 'total' => 3,
115 | 'slug' => 'color_red',
116 | 'http_query' => 'main-color%5B1%5D=red&sizes%5B0%5D=small'
117 | ]
118 | */
119 | ```
120 |
121 | ### Basic frontend example
122 |
123 | Here's a simple [demo project](https://github.com/mgussekloo/Facet-Demo) that demonstrates a basic frontend.
124 |
125 | ``` html
126 |