WPfaker Addon Development

Addon Plugin Structure

Minimal directory layout for a WPfaker addon WordPress plugin:

my-wpfaker-addon/
├── my-wpfaker-addon.php          # Plugin entry point
├── src/
│   ├── Adapters/
│   │   └── MyAdapter.php         # FieldPluginAdapterInterface implementation
│   └── AiProviders/
│       └── MyAiProvider.php      # AiProviderInterface implementation (optional)
├── tests/
│   └── Unit/
│       └── MyAdapterTest.php
├── composer.json
└── readme.txt

Entry Point Pattern

The addon MUST wait for the wpfaker_loaded action before registering anything. This ensures WPfaker classes and contracts are available.

<?php
/**
 * Plugin Name: My WPfaker Addon
 */

add_action('wpfaker_loaded', function (string $version) {
    // Register a custom field adapter
    add_action('wpfaker_register_adapters', function () {
        \WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);
    });

    // Register a custom AI provider (optional)
    add_action('wpfaker_register_ai_providers', function () {
        \WPFaker\Services\AiProviderFactory::register('my_ai', MyAiProvider::class, 'My AI Service');
    });
});

Registering a Custom Field Adapter

Your adapter must implement \WPFaker\Contracts\FieldPluginAdapterInterface. The adapter constructor receives a FakerService instance.

Required Methods

Method	Return	Purpose
isActive()	bool	Return true if your field plugin is active
getName()	string	Human-readable plugin name
getVersion()	string	Plugin version string
getCustomPostTypes()	array	CPTs registered by the plugin
getCustomTaxonomies()	array	Taxonomies registered by the plugin
getFieldGroups()	array	All field group configs
getFieldGroupsForPostType(string $postType)	array	Field groups for a specific CPT
getFields($fieldGroupId)	array	Fields within a group
getFieldsForPostType(string $postType)	array	All fields for a CPT
saveFieldValue(int $postId, string $fieldName, $value)	bool	Save a field value
getFieldConfig(string $fieldNameOrKey)	?array	Get field config by name
mapFieldTypeToFaker(array $field)	string	Map field type to Faker method
getSupportedFieldTypes()	array	List of supported field type slugs
setCptContext(string $slug, ?string $label)	self	Set CPT context for detection

Registration

\WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);

Registering a Custom AI Provider

Your provider must implement \WPFaker\Contracts\AiProviderInterface. Custom providers auto-appear in the Settings dropdown once registered.

Required Methods

Method	Return	Purpose
getProviderKey()	string	Unique key
getProviderName()	string	Display name for Settings UI
isAvailable()	bool	Has API key + is enabled
isEnabled()	bool	Is enabled regardless of key
getMaskedApiKey()	string	Masked API key for display
detectFieldType(...)	?array	Single field detection
detectFieldsBatch(...)	?array	Batch field detection
detectFieldsBatchWithConfig(...)	?array	Batch with faker configs
generateTitleTemplates(...)	?array	Generate title templates
generateCptContext(...)	?array	Generate CPT context
testConnection()	array	Test API connection

Registration

\WPFaker\Services\AiProviderFactory::register('my_ai', MyAiProvider::class, 'My AI Service');

Available Hooks

Actions

Hook	Parameters	Purpose
wpfaker_loaded	string $version	WPfaker fully loaded, addon entry point
wpfaker_register_adapters	none	Time to register custom adapters
wpfaker_register_ai_providers	none	Time to register custom AI providers
wpfaker_activate	none	Plugin activated
wpfaker_deactivate	bool $deleteData	Plugin deactivated
wpfaker_after_generate_item	string $type, int $id, int $index, int $total, array $options	After each item generated
wpfaker_after_generate	string $type, array $ids, array $options	After all items in batch

Filters

Hook	Parameters	Purpose
wpfaker_post_data	array $postData, string $postType, int $index, int $total, array $options	Modify post data before wp_insert_post
wpfaker_field_value	mixed $value, array $config, string $postType, int $postId	Modify field value before save
wpfaker_adapter_priority	array $priority	Change adapter resolution order
wpfaker_field_name_detection_enabled	bool $enabled	Enable/disable field name detection

Testing Pattern

Use Pest PHP with source-check patterns for adapter tests. Use AdapterFactory::resetRegistry() between tests for isolation:

beforeEach(function () {
    \WPFaker\Services\AdapterFactory::resetRegistry();
});

it('registers the adapter', function () {
    \WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);

    expect(\WPFaker\Services\AdapterFactory::has('my_plugin'))->toBeTrue();
});

Key Classes

• \WPFaker\Services\AdapterFactory — Registry for field plugin adapters
• \WPFaker\Services\AiProviderFactory — Registry for AI providers
• \WPFaker\Contracts\FieldPluginAdapterInterface — Contract for field adapters
• \WPFaker\Contracts\AiProviderInterface — Contract for AI providers
• \WPFaker\Services\FakerService — Core faker data generation service (injected into adapters)