| 1 |
<?php |
| 2 |
/** |
| 3 |
* Server-side opt-in for dock rail renderer scripts. |
| 4 |
* |
| 5 |
* Mirrors `includes/commands.php` exactly — a plugin enqueues a JS |
| 6 |
* bundle that registers a renderer with `wp.os.registerDockRailRenderer()`, |
| 7 |
* then calls `openstation_register_dock_rail_renderer_script( $handle )` |
| 8 |
* to opt the script into the live-refresh payload. The shell loads |
| 9 |
* the script over the chromeless bridge on activation, the JS calls |
| 10 |
* `registerDockRailRenderer()`, and the OS Settings → Dock style picker |
| 11 |
* surfaces the new option immediately — no F5. |
| 12 |
* |
| 13 |
* On deactivation (handle disappears from the payload), every renderer |
| 14 |
* tagged with `owner: '<handle>'` is unregistered. The active id falls |
| 15 |
* back through the registry's chain (user pick → `default`) and the |
| 16 |
* dispatcher rebuilds the rails with whatever resolves. |
| 17 |
* |
| 18 |
* @package OpenStation |
| 19 |
*/ |
| 20 |
|
| 21 |
defined( 'ABSPATH' ) || exit; |
| 22 |
|
| 23 |
/** |
| 24 |
* Register a script handle that contributes a dock rail renderer. |
| 25 |
* |
| 26 |
* Example: |
| 27 |
* |
| 28 |
* ```php |
| 29 |
* add_action( 'openstation_shell_assets', function () { |
| 30 |
* wp_register_script( |
| 31 |
* 'orbit-rail', |
| 32 |
* plugin_dir_url( __FILE__ ) . 'orbit-rail.js', |
| 33 |
* array( 'openstation' ), |
| 34 |
* '1.0.0', |
| 35 |
* true |
| 36 |
* ); |
| 37 |
* wp_enqueue_script( 'orbit-rail' ); |
| 38 |
* } ); |
| 39 |
* openstation_register_dock_rail_renderer_script( 'orbit-rail' ); |
| 40 |
* ``` |
| 41 |
* |
| 42 |
* The script's JS side calls `wp.os.registerDockRailRenderer( { … } )` |
| 43 |
* with `owner: 'orbit-rail'` (matching the handle) so deactivation |
| 44 |
* cleanly removes the renderer. |
| 45 |
* |
| 46 |
* @param string $handle WP-registered script handle. |
| 47 |
* @return true|WP_Error `true` on success; `WP_Error` on validation failure. |
| 48 |
*/ |
| 49 |
function openstation_register_dock_rail_renderer_script( $handle ) { |
| 50 |
$handle = (string) $handle; |
| 51 |
if ( '' === $handle ) { |
| 52 |
return openstation_registration_error( |
| 53 |
'openstation_missing_handle', |
| 54 |
__( 'Dock rail renderer script registration requires a non-empty script handle.', 'desktop-mode' ) |
| 55 |
); |
| 56 |
} |
| 57 |
|
| 58 |
openstation_dock_rail_renderer_script_registry( $handle, true ); |
| 59 |
|
| 60 |
/** |
| 61 |
* Fires after a desktop dock rail renderer script handle is registered. |
| 62 |
* |
| 63 |
* @param string $handle The registered script handle. |
| 64 |
*/ |
| 65 |
do_action( 'openstation_dock_rail_renderer_script_registered', $handle ); |
| 66 |
|
| 67 |
return true; |
| 68 |
} |
| 69 |
|
| 70 |
/** |
| 71 |
* Internal module-level registry for dock rail renderer script handles. |
| 72 |
* Read by the payload builder, written by the registration API. |
| 73 |
* |
| 74 |
* @internal |
| 75 |
* |
| 76 |
* @param string $handle Script handle to read or write. |
| 77 |
* @param bool|null $value Pass `true` to register; `null` to read only. |
| 78 |
* @return array|bool When called with no args returns the full store. |
| 79 |
*/ |
| 80 |
function openstation_dock_rail_renderer_script_registry( $handle = '', $value = null ) { |
| 81 |
static $store = array(); |
| 82 |
|
| 83 |
if ( '__flush__' === (string) $handle ) { |
| 84 |
$store = array(); |
| 85 |
return array(); |
| 86 |
} |
| 87 |
if ( '' === (string) $handle ) { |
| 88 |
return $store; |
| 89 |
} |
| 90 |
if ( null !== $value ) { |
| 91 |
$store[ (string) $handle ] = (bool) $value; |
| 92 |
} |
| 93 |
return isset( $store[ (string) $handle ] ) ? $store[ (string) $handle ] : false; |
| 94 |
} |
| 95 |
|
| 96 |
/** |
| 97 |
* Test-only: clear the registry between PHPUnit cases. See |
| 98 |
* {@see openstation_flush_script_handle_registries()}. |
| 99 |
*/ |
| 100 |
function openstation_flush_dock_rail_renderer_script_registry() { |
| 101 |
openstation_dock_rail_renderer_script_registry( '__flush__' ); |
| 102 |
} |
| 103 |
|
| 104 |
/** |
| 105 |
* Build the payload fed to the shell. Resolves each registered handle |
| 106 |
* to a full `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, |
| 107 |
* scriptTranslations }` entry; handles that aren't currently enqueued |
| 108 |
* (plugin not active this request) resolve to an empty URL and are |
| 109 |
* dropped. |
| 110 |
* |
| 111 |
* @return array[] |
| 112 |
*/ |
| 113 |
function openstation_build_dock_rail_renderer_scripts_payload() { |
| 114 |
$registry = openstation_dock_rail_renderer_script_registry(); |
| 115 |
if ( ! is_array( $registry ) || empty( $registry ) ) { |
| 116 |
return array(); |
| 117 |
} |
| 118 |
|
| 119 |
$out = array(); |
| 120 |
$seen = array(); |
| 121 |
foreach ( $registry as $handle => $active ) { |
| 122 |
if ( ! $active || isset( $seen[ $handle ] ) ) { |
| 123 |
continue; |
| 124 |
} |
| 125 |
$payload = openstation_resolve_script_payload( $handle ); |
| 126 |
if ( '' === $payload['url'] ) { |
| 127 |
openstation_warn_unresolvable_script_handle( |
| 128 |
'openstation_register_dock_rail_renderer_script', |
| 129 |
'Dock rail renderer', |
| 130 |
(string) $handle |
| 131 |
); |
| 132 |
continue; |
| 133 |
} |
| 134 |
$out[] = array( |
| 135 |
'handle' => (string) $handle, |
| 136 |
'scriptUrl' => $payload['url'], |
| 137 |
'scriptBefore' => $payload['before'], |
| 138 |
'scriptAfter' => $payload['after'], |
| 139 |
'scriptL10n' => $payload['l10n'], |
| 140 |
'scriptTranslations' => $payload['translations'], |
| 141 |
); |
| 142 |
$seen[ $handle ] = true; |
| 143 |
} |
| 144 |
return $out; |
| 145 |
} |
| 146 |
|
