PHPackages                             danlapteacru/facetwp-builder - 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. [Templating & Views](/categories/templating)
4. /
5. danlapteacru/facetwp-builder

ActivePackage[Templating & Views](/categories/templating)

danlapteacru/facetwp-builder
============================

An Advanced FacetWP Builder for facets and templates.

0.2.0(4mo ago)49[1 PRs](https://github.com/danlapteacru/facetwp-builder/pulls)MITPHPPHP ^8.1CI passing

Since Aug 2Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/danlapteacru/facetwp-builder)[ Packagist](https://packagist.org/packages/danlapteacru/facetwp-builder)[ Docs](https://github.com/itinerisltd/facetwp-builder/)[ RSS](/packages/danlapteacru-facetwp-builder/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (1)Versions (6)Used By (0)

FacetWP Builder
===============

[](#facetwp-builder)

Create, register, and reuse [FacetWP](https://facetwp.com/) plugin facets/templates using PHP, and keep them in your source code repository. To read more about registering FacetWP facets and templates via PHP, go here: [facets documentation](https://facetwp.com/help-center/developers/hooks/advanced-hooks/facetwp_facets/) and [templates documentation](https://facetwp.com/help-center/developers/hooks/advanced-hooks/facetwp_templates/).

[![Packagist Version](https://camo.githubusercontent.com/6bd0df43ae5ba27ded2567cf801eb70e70a4465901f15036aca30aff8ec65c3d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64616e6c61707465616372752f666163657477702d6275696c6465722e7376673f6c6162656c3d72656c65617365267374796c653d666c61742d737175617265)](https://packagist.org/packages/danlapteacru/facetwp-builder)[![PHP from Packagist](https://camo.githubusercontent.com/7f3a99414bd20a2f36502dd4a538442d1d6aaaec5cfadbdf5de8a557f7354bc0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f64616e6c61707465616372752f666163657477702d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/danlapteacru/facetwp-builder)[![Packagist Downloads](https://camo.githubusercontent.com/fab0e6de4473e20faf56dab52be80e5060ab1ba8a55beca2996f2d6f8d9fa4d3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f64616e6c61707465616372752f666163657477702d6275696c6465722e7376673f6c6162656c3d7061636b6167697374253230646f776e6c6f616473267374796c653d666c61742d737175617265)](https://packagist.org/packages/danlapteacru/facetwp-builder/stats)[![GitHub License](https://camo.githubusercontent.com/c279883954573ad3c89d6102b218a84a88ffeb191a9244a3a43adef924902454/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f64616e6c61707465616372752f666163657477702d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://github.com/danlapteacru/facetwp-builder/blob/master/LICENSE)

- [Minimum Requirements](#minimum-requirements)
- [Installation](#installation)
- [Adding/Removing FacetWP Facets and Templates with the Builder](#addingremoving-facetwp-facets-and-templates-with-the-builder)
- [Composing Custom/3rd Party Addon Facets](#composing-custom3rd-party-addon-facets)
- [Hooks](#hooks)
- [Examples](#examples)
- [Credits](#credits)
- [License](#license)

Minimum Requirements
--------------------

[](#minimum-requirements)

- PHP v8.1
- WordPress v6.1
- [FacetWP](https://facetwp.com) v4.0

Installation
------------

[](#installation)

```
composer require danlapteacru/facetwp-builder
```

If your project isn't using composer, you can require the `autoload.php` file.

Adding/Removing FacetWP Facets and Templates with the Builder
=============================================================

[](#addingremoving-facetwp-facets-and-templates-with-the-builder)

Table of Contents
-----------------

[](#table-of-contents)

[Facets](#facets)[Templates](#templates)[Autocomplete](#autocomplete)[Add a template](#add-a-template)[Checkbox](#checkbox)[Date Range](#date-range)[Dropdown](#dropdown)[fSelect](#fselect)[Hierarchy](#hierarchy)[Number Range](#number-range)[Pager](#pager)[Proximity](#proximity)[Radio](#radio)[Reset](#reset)[Search](#search)[Slider](#slider)[Sort](#sort)[Star Rating](#star-rating)[User Selections](#user-selections)### Facet Types

[](#facet-types)

You can find a full reference of available facets on the [official FacetWP documentation](https://facetwp.com/help-center/facets/facet-types/).

#### Autocomplete

[](#autocomplete)

```
$builder->addAutocomplete('autocomplete', [
    'label' => 'Autocomplete',
    'source' => 'post_title',
    'placeholder' => 'Placeholder',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/autocomplete/)

#### Checkboxes

[](#checkboxes)

```
$builder->addCheckbox('checkbox', [
    'label' => 'Categories',
    'source' => 'tax/category',
    'parent_term' => '',
    'hierarchical' => 'no',
    'show_expanded' => 'no',
    'ghosts' => 'no',
    'preserve_ghosts' => 'no',
    'operator' => 'and',
    'orderby' => 'count',
    'count' => '10',
    'soft_limit' => '5',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/checkboxes/)

#### Date Range

[](#date-range)

```
$builder->addDateRange('date_range', [
    'label' => 'Date Range',
    'source' => 'post_date',
    'compare_type' => '',
    'fields' => 'both',
    'format' => '',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/date-range/)

#### Dropdown

[](#dropdown)

```
$builder->addDropdown('dropdown', [
    'label' => 'Dropdown',
    'source' => 'tax/category',
    'label_any' => 'Any',
    'parent_term' => '',
    'modifier_type' => 'off',
    'modifier_values' => '',
    'hierarchical' => 'no',
    'orderby' => 'count',
    'count' => '10',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/dropdown/)

#### fSelect

[](#fselect)

```
$builder->addFselect('fselect', [
    'label' => 'fSelect',
    'source' => 'tax/category',
    'label_any' => 'Any',
    'parent_term' => '',
    'modifier_type' => 'off',
    'modifier_values' => '',
    'hierarchical' => 'no',
    'multiple' => 'no',
    'ghosts' => 'no',
    'preserve_ghosts' => 'no',
    'operator' => 'and',
    'orderby' => 'count',
    'count' => '10',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/fselect/)

#### Hierarchy

[](#hierarchy)

```
$builder->addHierarchy('hierarchy', [
    'label' => 'Hierarchy',
    'source' => 'tax/category',
    'label_any' => 'Any',
    'modifier_type' => 'off',
    'modifier_values' => '',
    'orderby' => 'count',
    'soft_limit' => '5',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/hierarchy/)

#### Number Range

[](#number-range)

```
$builder->addNumberRange('number_range', [
    'label' => 'Number Range',
    'source' => 'post_meta/price',
    'compare_type' => '',
    'fields' => 'both',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/number-range/)

#### Pager

[](#pager)

```
$builder->addPager('pager', [
    'label' => 'Pager',
    'pager_type' => 'numbers',
    'inner_size' => '2',
    'dots_label' => '…',
    'prev_label' => '« Prev',
    'next_label' => 'Next »',
    'count_text_plural' => '[lower] - [upper] of [total] results',
    'count_text_singular' => '1 result',
    'count_text_none' => 'No results',
    'load_more_text' => 'Load more',
    'loading_text' => 'Loading...',
    'default_label' => 'Per page',
    'per_page_options' => '10, 25, 50, 100',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/pager/)

#### Proximity

[](#proximity)

```
$builder->addProximity('proximity', [
    'label' => 'Proximity',
    'source' => 'post_meta/location',
    'unit' => 'mi',
    'radius_ui' => 'dropdown',
    'radius_options' => '10, 25, 50, 100, 250',
    'radius_min' => '1',
    'radius_max' => '50',
    'radius_default' => '25',
    'placeholder' => '',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/proximity/)

#### Radio

[](#radio)

```
$builder->addRadio('radio', [
    'label' => 'Radio',
    'source' => 'tax/category',
    'label_any' => 'Any',
    'parent_term' => '',
    'modifier_type' => 'off',
    'modifier_values' => '',
    'ghosts' => 'no',
    'preserve_ghosts' => 'no',
    'orderby' => 'count',
    'count' => '10',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/radio/)

#### Reset

[](#reset)

```
$builder->addReset('reset', [
    'label' => 'Reset',
    'reset_ui' => 'button',
    'reset_text' => 'Reset',
    'reset_mode' => 'off',
    'auto_hide' => 'no',
    'reset_facets' => [],
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/reset/)

#### Search

[](#search)

```
$builder->addSearch('search', [
    'label' => 'Search',
    'search_engine' => '',
    'placeholder' => '',
    'auto_refresh' => 'no',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/search/)

#### Slider

[](#slider)

```
$builder->addSlider('slider', [
    'label' => 'Slider',
    'source' => 'post_meta/price',
    'compare_type' => '',
    'prefix' => '',
    'suffix' => '',
    'reset_text' => 'Reset',
    'format' => '0,0',
    'step' => '1',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/slider/)

#### Sort

[](#sort)

```
$builder->addSort('sort', [
    'label' => 'Sort',
    'default_label' => 'Sort by',
    'sort_options' => [
        [
            'label' => 'Title (A-Z)',
            'name' => 'title_asc',
            'orderby' => [
                [
                    'key' => 'title',
                    'order' => 'ASC',
                    'type' => 'CHAR',
                ],
            ],
        ],
    ],
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/sort/)

#### Star Rating

[](#star-rating)

```
$builder->addRating('star_rating', [
    'label' => 'Star Rating',
    'source' => 'post_meta/rating',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/rating/)

#### User Selections

[](#user-selections)

```
$builder->addUserSelections('user_selections', [
    'label' => 'User Selections',
]);
```

[Official Documentation](https://facetwp.com/help-center/facets/facet-types/user-selections/)

### Facet shortcut methods

[](#facet-shortcut-methods)

Instead of passing all options as an array to the add method, you can chain setter methods on the returned `FacetBuilder`. All setters transform values automatically (booleans become `'yes'`/`'no'` strings).

```
setName(string $name)
setLabel(string $label)
setSource(string $source)
setOperator(string $operator)
setOrderby(string $orderby)
setCount(int $count)
setHierarchical(bool $hierarchical)
setShowExpanded(bool $show_expanded)
setGhosts(bool $ghosts)
setPreserveGhosts(bool $preserve_ghosts)
setSoftLimit(int $soft_limit)
setLabelAny(string $label_any)
setMultiple(bool $multiple)
setSearchEngine(string $search_engine)
setPlaceholder(string $placeholder)
setAutoRefresh(bool $auto_refresh)
setStep(int $step)
setPrefix(string $prefix)
setSuffix(string $suffix)
setCompareType(string $compare_type)
setFormat(string $format)
setSourceOther(string $source_other)
```

For custom/arbitrary attributes not in the list above, use `setAttr(string $name, mixed $value)` directly.

### Managing facets

[](#managing-facets)

`FacetsBuilder` exposes the following methods for working with its facet collection:

```
// Add all facets from another FacetsBuilder or a plain array
$builder->addFacets(array|FacetsBuilder $facets): static

// Retrieve facets
$builder->getFacets(): FacetBuilder[]
$builder->getFacet(string $name): FacetBuilder   // throws FacetNotFoundException

// Check existence
$builder->facetExists(string $name): bool
```

### Building and registering

[](#building-and-registering)

Calling `build()` on the `FacetsBuilder` compiles the config and — by default — registers facets with FacetWP via the `facetwp_facets` WordPress filter.

```
// Register with FacetWP (default)
$builder->build();

// Only build the array, skip WP hook registration
$builder->build(addArrayToWpHook: false);

// Register a pre-built array manually
FacetsBuilder::addFacetWpHook(array $facets): void
```

**Note:** calling `build()` on the `FacetBuilder` returned by `addSearch()` / `addCheckbox()` / etc. builds only that single facet's config array and does **not** register anything with WordPress. Always call `$builder->build()` on the `FacetsBuilder` instance to register.

### Templates

[](#templates)

You can find a full reference of how to add a template with PHP on the [official FacetWP documentation](https://facetwp.com/help-center/developers/hooks/advanced-hooks/facetwp_templates/).

#### Add a template

[](#add-a-template)

Use `addTemplate(string $name, array $args = [])` to add a template. It returns a `TemplateBuilder` for further configuration.

Example using the array form:

```
$builder->addTemplate('course', [
    'label' => 'Course',
    'query_array' => [
        'post_type' => 'course',
        'post_status' => 'publish',
        'posts_per_page' => 10,
        'orderby' => 'title',
        'order' => 'ASC',
    ],
    'modes' => [
        'display' => 'visual',
        'query' => 'advanced',
    ],
]);
```

**Attention!** The `query` key must contain a PHP code string. Use the `setQuery()` helper instead to pass a plain array and have it converted automatically.

#### Template shortcut methods

[](#template-shortcut-methods)

```
setName(string $name)
setLabel(string $label)
setQuery(array $query)       // converts array to PHP string automatically
setQueryObj(array $query)
setLayout(array $layout)
setModes(array $modes)
setPostType(string $postType)       // throws Exception if post type not found
setPostsPerPage(int $postsPerPage)
```

Example using chainable setters:

```
$builder
    ->addTemplate('course')
    ->setLabel('Course')
    ->setQuery([
        'post_type' => 'course',
        'post_status' => 'publish',
        'posts_per_page' => 10,
        'orderby' => 'title',
        'order' => 'ASC',
    ])
    ->setModes([
        'display' => 'visual',
        'query' => 'advanced',
    ]);
$builder->build();
```

`setPostType()` and `setPostsPerPage()` are convenience helpers that update both `query` and `query_obj` in one call:

```
$builder
    ->addTemplate('course')
    ->setPostType('course')
    ->setPostsPerPage(9);
$builder->build();
```

##### Default label

[](#default-label)

If `setLabel()` is not called and no `label` key is passed to `addTemplate()`, the label is auto-generated from the template name.

##### Default modes

[](#default-modes)

If `setModes()` is not called and no `modes` key is passed, the following defaults are used:

```
[
    'display' => 'visual',
    'query' => 'advanced',
]
```

### Managing templates

[](#managing-templates)

`TemplatesBuilder` exposes the following methods for working with its template collection:

```
// Add all templates from another TemplatesBuilder or a plain array
$builder->addTemplates(array|TemplatesBuilder $templates): static

// Retrieve templates
$builder->getTemplates(): TemplateBuilder[]
$builder->getTemplate(string $name): TemplateBuilder   // throws FacetNotFoundException

// Check existence
$builder->templateExists(string $name): bool
```

### Building and registering templates

[](#building-and-registering-templates)

```
// Register with FacetWP (default)
$builder->build();

// Only build the array, skip WP hook registration
$builder->build(addTemplatesToWpHook: false);

// Register a pre-built array manually
TemplatesBuilder::addFacetWpHook(array $templates): void
```

Composing Custom/3rd Party Addon Facets
---------------------------------------

[](#composing-custom3rd-party-addon-facets)

Use `addFacet(string $name, string $type, array $args = [])` to add a facet with an arbitrary type string.

```
$builder->addFacet('my_facet', 'checkbox', [
    'label' => 'My Facet Label',
]);
```

To use a type not in the built-in [`ALLOWED_FACET_TYPES`](https://github.com/danlapteacru/facetwp-builder/blob/main/src/FacetsBuilder.php#L66) constant, register it via the [`danlapteacru/facetwp-builder/allowed_facet_types`](#danlapteacrufacetwp-builderallowed_facet_types) filter hook.

Hooks
-----

[](#hooks)

### `danlapteacru/facetwp-builder/allowed_facet_types`

[](#danlapteacrufacetwp-builderallowed_facet_types)

Filter the list of allowed facet types. Use this to add support for custom or 3rd-party addon types.

```
add_filter('danlapteacru/facetwp-builder/allowed_facet_types', function (array $types): array {
    $types[] = 'my_custom_type';
    return $types;
});
```

### `danlapteacru/facetwp-builder/facets`

[](#danlapteacrufacetwp-builderfacets)

Filter the compiled facets array before it is returned by `FacetsBuilder::build()`.

### `danlapteacru/facetwp-builder/facet_key`

[](#danlapteacrufacetwp-builderfacet_key)

Filter the resolved facet type key before it is validated inside `FacetsBuilder::__call()`. Useful for aliasing method names to custom type strings.

### `danlapteacru/facetwp-builder/templates`

[](#danlapteacrufacetwp-buildertemplates)

Filter the compiled templates array before it is returned by `TemplatesBuilder::build()`.

Examples
--------

[](#examples)

### Table of Contents

[](#table-of-contents-1)

Examples[Add Facets](#add-facets)[Add a custom facet](#add-a-custom-facet)[Add Template](#add-template)### Add Facets

[](#add-facets)

```
use DanLapteacru\FacetWpBuilder\FacetsBuilder;

$builder = new FacetsBuilder();
$builder
    ->addSearch('search')
    ->setLabel('Search')
    ->setPlaceholder('Search placeholder')
    ->setAutoRefresh(true);
$builder->build();
```

### Add a custom facet

[](#add-a-custom-facet)

```
use DanLapteacru\FacetWpBuilder\FacetBuilder;
use DanLapteacru\FacetWpBuilder\Facets\Checkbox;
use DanLapteacru\FacetWpBuilder\FacetsBuilder;

$facet = new FacetBuilder('my_facet', Checkbox::TYPE);
$facet
    ->setLabel('Categories')
    ->setSource('tax/category');
$facetArray = $facet->build();

FacetsBuilder::addFacetWpHook($facetArray);
```

### Add Template

[](#add-template)

```
use DanLapteacru\FacetWpBuilder\TemplatesBuilder;

$builder = new TemplatesBuilder();
$builder
    ->addTemplate('course')
    ->setLabel('Courses')
    ->setQuery([
        'post_type' => 'course',
        'post_status' => 'publish',
        'posts_per_page' => 8,
        'orderby' => 'title',
        'order' => 'ASC',
    ]);
$builder->build();
```

Credits
-------

[](#credits)

[FacetWP Builder](https://github.com/danlapteacru/facetwp-builder) is created and maintained by [Dan Lapteacru](https://github.com/danlapteacru).

Full list of contributors can be found [here](https://github.com/danlapteacru/facetwp-builder/graphs/contributors).

License
-------

[](#license)

[FacetWP Builder](https://github.com/danlapteacru/facetwp-builder) is released under the [MIT License](https://opensource.org/licenses/MIT).

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance79

Regular maintenance activity

Popularity9

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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

Every ~932 days

Total

2

Last Release

133d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6186169?v=4)[Dan Lapteacru](/maintainers/danlapteacru)[@danlapteacru](https://github.com/danlapteacru)

---

Top Contributors

[![danlapteacru](https://avatars.githubusercontent.com/u/6186169?v=4)](https://github.com/danlapteacru "danlapteacru (25 commits)")

### Embed Badge

![Health badge](/badges/danlapteacru-facetwp-builder/health.svg)

```
[![Health](https://phpackages.com/badges/danlapteacru-facetwp-builder/health.svg)](https://phpackages.com/packages/danlapteacru-facetwp-builder)
```

###  Alternatives

[limenius/react-bundle

Client and Server-side react rendering in a Symfony Bundle

3851.2M](/packages/limenius-react-bundle)[area17/laravel-auto-head-tags

Laravel Auto Head Tags helps you build the list of head elements for your app

4616.1k](/packages/area17-laravel-auto-head-tags)[jelix/wikirenderer

WikiRenderer is a library to generate HTML or anything else from wiki content.

1712.3k1](/packages/jelix-wikirenderer)[webkinder/sproutset

A Composer package for handling responsive images in Roots Bedrock + Sage + Blade projects.

282.2k](/packages/webkinder-sproutset)

PHPackages © 2026

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