Skip to main content
Providers are the backbone of serving data. They handle how data is stored, indexed, and retrieved for search operations.

​
ProviderInterface

use Nadir\MerchantBuddy\Providers\Contracts\ProviderInterface;
All providers must implement the ProviderInterface. This interface defines the core functionality required for any search provider.
​
get_provider_label(): string
string
Returns the publicly readable, translatable name for the provider. This is used in the settings page and UI.
​
get_provider_slug(): string
string
Returns a unique identifier for the provider. This is used for persisting settings and provider identification.
​
is_ready(): bool
bool
Returns whether the provider is properly configured and ready to be used.
​
create_item(array $item_data, int $item_id, string $entity_name): bool
bool
Creates a new item in the provider’s data storage.
​
update_item(array $item_data, int $item_id, string $entity_name): bool
bool
Updates an existing item in the provider’s data storage.
​
delete_item(int $item_id, string $entity_name): bool
bool
Removes an item from the provider’s data storage.

​
HasSettings

use Nadir\MerchantBuddy\Providers\Contracts\HasSettings;
The HasSettings trait can be used by providers that need to expose configuration options in the settings page.
​
get_settings_fields(): array
array
default:"[]"
Returns an array of settings fields to be displayed in the settings page. See Fields section below for structure.
​
has_settings(): bool
bool
default:"true"
Indicates if the provider has configurable settings. Defaults to true.
​
get_settings(): array
array
Returns the saved settings values for the provider. Uses the WordPress option name merchant_buddy_{provider_slug}_settings.
​
get_description(): string|array
string|array
Returns the provider’s description for the settings page. Can return either: - A string: Simple description text - An array: Structured description with optional external link
[
  'description' => 'Description text',
  'link' => [
    'text' => 'Link text',
    'url' => 'https://example.com',
  ],
]

​
Fields

Settings fields are defined as arrays with the following structure:
​
title
string
The human-readable label for the field.
​
type
string
default:"text"
The field type. Can be one of: text, password, checkbox, or select.
​
name
string
The unique identifier for the field. Used to store and retrieve the value.
​
description
string
Help text explaining the purpose of the field.
​
public
bool
default:"true"
Whether the field’s value should be exposed to the frontend. If true, the value will be available at window.searchBuddy[providerSlug][fieldName].
​
options
array
Required for select type fields. An array of options in the format:
[
  ['label' => 'Human Label', 'value' => 'stored_value'],
  ['label' => 'Human Label', 'value' => 'stored_value'],
]

​
Batchable

use Nadir\MerchantBuddy\Providers\Contracts\Batchable;
Providers that support batch operations should implement the Batchable interface. This enables efficient bulk operations for creating, updating, and deleting multiple items at once.
​
batch_add_items(array $items, string $index_name): bool
bool
Adds multiple items to the provider’s storage in a single operation.
​
batch_update_items(array $items, string $index_name): bool
bool
Updates multiple items in the provider’s storage in a single operation.
​
batch_delete_items(array $item_ids, string $index_name): bool
bool
Deletes multiple items from the provider’s storage in a single operation.

​
Provider (TypeScript)

On the frontend, providers need to implement the Provider interface: 
interface Provider {
  id: string;
  search: (
    query: string,
    entity: string,
    signal?: AbortSignal
  ) => Promise<Item[]>;
  searchAll: (
    query: string,
    signal?: AbortSignal
  ) => Promise<Record<string, Item[]>>;
}
​
id
string
The provider’s unique identifier, matching the PHP provider’s slug.
​
search
function
Searches for items within a specific entity
​
searchAll
function
Searches across all entities

​
Item Interface

Search results must include at minimum: 
interface Item extends Record<string, unknown> {
  id: number;
  name: string;
}