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 alladd_actionandadd_filtercalls.Activator/Deactivator: (Internal) Handles one-time setup tasks like database migrations or flushing rewrite rules. Do not call these directly.