| 1 |
<?php |
| 2 |
|
| 3 |
if (!defined('ABSPATH')) { |
| 4 |
exit; |
| 5 |
} |
| 6 |
|
| 7 |
/** |
| 8 |
* Contract for one admin action handler. |
| 9 |
* |
| 10 |
* Each handler corresponds 1:1 with a string action name (or prefix) submitted |
| 11 |
* via a wp-admin POST/GET to the plugin's options page. The dispatcher |
| 12 |
* (ABJ_404_Solution_PluginLogicAdminActions::handlePluginAction) centralizes |
| 13 |
* the nonce + is_admin() guard. Each handler owns only its action's specific |
| 14 |
* work, and returns the message that should be displayed back to the admin. |
| 15 |
* |
| 16 |
* Why the interface is needed: |
| 17 |
* - Replaces a 12-branch if/else chain in PluginLogicAdminActions, where each |
| 18 |
* branch repeated `check_admin_referer + is_admin + dispatch + debug-log |
| 19 |
* on failure`. Centralizing those guards in the dispatcher makes it |
| 20 |
* impossible to forget the nonce check for a new action. |
| 21 |
* |
| 22 |
* Implementations: |
| 23 |
* - includes/admin/actions/*Handler.php (one class per action verb). |
| 24 |
*/ |
| 25 |
interface ABJ_404_Solution_AdminActionHandlerInterface { |
| 26 |
|
| 27 |
/** |
| 28 |
* The nonce action string this handler expects (passed to wp_verify_nonce / |
| 29 |
* check_admin_referer in the dispatcher). |
| 30 |
* |
| 31 |
* @return string |
| 32 |
*/ |
| 33 |
public function nonceAction(): string; |
| 34 |
|
| 35 |
/** |
| 36 |
* The query/POST arg holding the nonce value. Default is '_wpnonce' (the |
| 37 |
* value used by check_admin_referer). One handler (SaveGscSettings) uses |
| 38 |
* a custom arg '_wpnonce_gsc'; UpdateOptions uses the POST field 'nonce'. |
| 39 |
* |
| 40 |
* @return string |
| 41 |
*/ |
| 42 |
public function nonceArg(): string; |
| 43 |
|
| 44 |
/** |
| 45 |
* Whether this handler uses check_admin_referer() (true) or the lower-level |
| 46 |
* wp_verify_nonce($_POST['<arg>'], ...) (false). Mirrors the pre-refactor |
| 47 |
* dispatch code exactly: only 'updateOptions' historically used |
| 48 |
* wp_verify_nonce() directly against $_POST['nonce']; everything else used |
| 49 |
* check_admin_referer(). |
| 50 |
* |
| 51 |
* @return bool |
| 52 |
*/ |
| 53 |
public function useCheckAdminReferer(): bool; |
| 54 |
|
| 55 |
/** |
| 56 |
* Run the action-specific work. |
| 57 |
* |
| 58 |
* @param string $action The action verb (passed in case a handler matches |
| 59 |
* multiple verbs, e.g. the bulk* prefix handler). |
| 60 |
* @param string $sub The current admin subpage (by reference; handler |
| 61 |
* may rewrite it, e.g. updateOptions sets it to |
| 62 |
* 'abj404_options'). |
| 63 |
* @return string Human-readable message to display, or '' for none. |
| 64 |
*/ |
| 65 |
public function handle(string $action, string &$sub): string; |
| 66 |
} |
| 67 |
|
