Plugin Design Patterns

Architectural Overview

To ensure consistency and maintainability across all WordPress contributions in this repository, we adhere to a set of standardized design patterns. These patterns focus on decoupling logic from the WordPress core while providing a predictable interface for extension.

The Singleton Entry Point

Each plugin is initialized via a Singleton pattern to prevent multiple instances and provide a centralized access point for the plugin's public methods.

Usage

To access the plugin instance and its public methods:

// Retrieve the main instance
$plugin = \UditAkhourii\ProjectName\Plugin::get_instance();

// Access a public service or method
$settings = $plugin->get_settings();

Service-Oriented Architecture

Functionality is divided into discrete Services. This prevents the main plugin file from becoming bloated and allows users to interact with specific modules independently.

Interacting with Services

Most plugins expose services via getter methods. These services handle specific domains like API integrations, database operations, or UI rendering.

| Service | Method | Return Type | Description | | :--- | :--- | :--- | :--- | | Settings | get_settings() | Settings_Service | Manages plugin options and metadata. | | API | get_api() | API_Client | Handles external requests and authentication. | | Logger | get_logger() | Log_Interface | Standardized debugging and error logging. |

Example:

$api_client = \UditAkhourii\ProjectName\Plugin::get_instance()->get_api();
$response = $api_client->fetch_data('endpoint_slug');

Action and Filter Hooks (Public API)

Following WordPress best practices, our plugins provide a "Hook-first" interface. This allows you to modify behavior without touching the source code.

Custom Filters

Filters are used to modify data before it is processed or rendered.

| Filter Name | Input Type | Description | | :--- | :--- | :--- | | ua_wp_{plugin}_config | array | Modifies the default configuration array. | | ua_wp_{plugin}_template_path | string | Overrides the default path for UI templates. |

Example:

add_filter('ua_wp_myplugin_config', function($config) {
    $config['timeout'] = 60; // Increase API timeout
    return $config;
});

Custom Actions

Actions are triggered at specific lifecycle events within the plugin.

| Action Name | Parameters | Description | | :--- | :--- | :--- | | ua_wp_{plugin}_initialized | Plugin Instance | Fires once the plugin and all services are loaded. | | ua_wp_{plugin}_before_save | array $data | Fires before data is persisted to the database. |

Standardized Configuration Object

Configurations are passed via a standardized object or array to ensure type safety and predictable defaults.

Configuration Schema

When initializing or extending a component, use the following schema:

| Property | Type | Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | enabled | boolean | No | true | Toggles the component state. | | version | string | Yes | N/A | The version string for asset versioning. | | db_prefix | string | No | ua_ | Prefix for custom table names. |

Error Handling

Our plugins use a standardized WP_Error wrapper for all public-facing methods. Instead of throwing raw exceptions, methods return a WP_Error object on failure.

Consumption Example

$result = \UditAkhourii\ProjectName\Plugin::get_instance()->process_data($payload);

if (is_wp_error($result)) {
    error_log($result->get_error_message());
    return;
}

// Proceed with success logic

Internal Components

While the following are internal to the plugin lifecycle, understanding their role helps when debugging:

• Loader: (Internal) Responsible for iterating through the Service Container and registering all add_action and add_filter calls.
• Activator/Deactivator: (Internal) Handles one-time setup tasks like database migrations or flushing rewrite rules. Do not call these directly.