README

Create, register, and reuse FacetWP 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 and templates documentation.

Minimum Requirements
Installation
Adding/Removing FacetWP Facets and Templates with the Builder
Composing Custom/3rd Party Addon Facets
Hooks
Examples
Credits
License

Minimum Requirements

PHP v8.1
WordPress v6.1
FacetWP v4.0

Installation

composer require itinerisltd/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

Facets	Templates
Autocomplete	Add a template
Checkbox
Date Range
Dropdown
fSelect
Hierarchy
Number Range
Pager
Proximity
Radio
Reset
Search
Slider
Sort
Star Rating
User Selections

Facet Types

You can find a full reference of available facets on the official FacetWP documentation.

Autocomplete

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

Official Documentation

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

Date Range

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

Official Documentation

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

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

Hierarchy

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

Official Documentation

Number Range

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

Official Documentation

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

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

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

Reset

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

Official Documentation

Search

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

Official Documentation

Slider

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

Official Documentation

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

Star Rating

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

Official Documentation

User Selections

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

Official Documentation

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

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

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

You can find a full reference of how to add a template with PHP on the official FacetWP documentation.

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

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

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

Default modes

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

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

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

// 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

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 constant, register it via the itinerisltd/facetwp-builder/allowed_facet_types filter hook.

Hooks

`itinerisltd/facetwp-builder/allowed_facet_types`

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

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

`itinerisltd/facetwp-builder/facets`

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

`itinerisltd/facetwp-builder/facet_key`

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

`itinerisltd/facetwp-builder/templates`

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

Examples

Examples
Add Facets
Add a custom facet
Add Template

Add Facets

use Itineris\FacetWpBuilder\FacetsBuilder;

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

Add a custom facet

use Itineris\FacetWpBuilder\FacetBuilder;
use Itineris\FacetWpBuilder\Facets\Checkbox;
use Itineris\FacetWpBuilder\FacetsBuilder;

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

FacetsBuilder::addFacetWpHook($facetArray);

Add Template

use Itineris\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

FacetWP Builder is maintained by Itineris, originally created by Dan Lapteacru.

Full list of contributors can be found here.

License

FacetWP Builder is released under the MIT License.

danlapteacru / facetwp-builder

Maintainers

Details

README

Minimum Requirements

Installation

Adding/Removing FacetWP Facets and Templates with the Builder

Table of Contents

Facet Types

Autocomplete

Checkboxes

Date Range

Dropdown

fSelect

Hierarchy

Number Range

Pager

Proximity

Radio

Reset

Search

Slider

Sort

Star Rating

User Selections

Facet shortcut methods

Managing facets

Building and registering

Templates

Add a template

Template shortcut methods

Default label

Default modes

Managing templates

Building and registering templates

Composing Custom/3rd Party Addon Facets

Hooks

itinerisltd/facetwp-builder/allowed_facet_types

itinerisltd/facetwp-builder/facets

itinerisltd/facetwp-builder/facet_key

itinerisltd/facetwp-builder/templates

Examples

Table of Contents

Add Facets

Add a custom facet

Add Template

Credits

License

`itinerisltd/facetwp-builder/allowed_facet_types`

`itinerisltd/facetwp-builder/facets`

`itinerisltd/facetwp-builder/facet_key`

`itinerisltd/facetwp-builder/templates`