zip-ai / inc / traits / enqueue.php

enqueue.php in ZIP AI – AI Website Builder & AI Agent (Beta) trunk, at inc/traits/enqueue.php

214 lines 5.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Enqueue Trait
4	*
5	* Reusable trait for enqueueing scripts, styles, translations,
6	* and localizing data with consistent handle prefixing.
7	*
8	* @package zip-ai
9	* @since 1.0.0
10	*/
11
12	namespace ZipAI\MCP\Classes\Traits;
13
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	/**
19	* Trait Enqueue.
20	*
21	* @method void wp_enqueue_scripts() Provided by the consuming class; registered on the wp_enqueue_scripts action.
22	*
23	* @since 1.0.0
24	*/
25	trait Enqueue {
26
27	/**
28	* Handle prefix for all enqueued assets.
29	*
30	* @var string
31	*/
32	public $enqueue_prefix = 'zip-ai';
33
34	/**
35	* Build path (absolute filesystem path).
36	*
37	* @var string
38	*/
39	public $build_path = ZIPAI_MCP_DIR . 'assets/';
40
41	/**
42	* Build URL.
43	*
44	* @var string
45	*/
46	public $build_url = ZIPAI_MCP_URL . 'assets/';
47
48	/**
49	* Language directory for translations.
50	*
51	* @var string
52	*/
53	public $language_dir = ZIPAI_MCP_DIR . 'languages';
54
55	/**
56	* Register frontend enqueue hook.
57	*
58	* @since 1.0.0
59	* @return void
60	*/
61	public function enqueue_scripts() {
62	add_action( 'wp_enqueue_scripts', array( $this, 'wp_enqueue_scripts' ) );
63	}
64
65	/**
66	* Register admin enqueue hook.
67	*
68	* @since 1.0.0
69	* @return void
70	*/
71	public function enqueue_scripts_admin() {
72	add_action( 'admin_enqueue_scripts', array( $this, 'admin_enqueue_scripts' ) );
73	}
74
75	/**
76	* Register, enqueue, localize, and set translations for a script.
77	*
78	* @param string $hook Handle suffix (prefixed automatically).
79	* @param string $path Full URL to the script file.
80	* @param array<string> $dependency Script dependencies.
81	* @param array{hook?: string, object_name?: string, data?: array<string, mixed>} $localization_array Localization config: [ 'hook' => '', 'object_name' => '', 'data' => [] ].
82	* @param string $version Asset version. Defaults to plugin version.
83	*
84	* @since 1.0.0
85	* @return void
86	*/
87	public function script_operations( $hook, $path, $dependency, $localization_array = array(), $version = ZIPAI_MCP_VERSION ) {
88	$this->register_script( $hook, $path, $dependency, $version );
89	$this->enqueue_script( $hook );
90
91	if ( ! empty( $localization_array['hook'] ) && ! empty( $localization_array['object_name'] ) && ! empty( $localization_array['data'] ) ) {
92	$this->localize_script( $localization_array['hook'], $localization_array['object_name'], $localization_array['data'] );
93	}
94
95	if ( function_exists( 'wp_set_script_translations' ) ) {
96	wp_set_script_translations(
97	$this->enqueue_prefix . '-' . $hook,
98	$this->enqueue_prefix,
99	$this->language_dir
100	);
101	}
102	}
103
104	/**
105	* Register and enqueue a style.
106	*
107	* @param string $hook Handle suffix (prefixed automatically).
108	* @param string $path Full URL to the CSS file.
109	* @param array<string> $dependency Style dependencies.
110	* @param string $version Asset version. Defaults to plugin version.
111	*
112	* @since 1.0.0
113	* @return void
114	*/
115	public function style_operations( $hook, $path, $dependency = array(), $version = ZIPAI_MCP_VERSION ) {
116	$this->register_style( $hook, $path, $dependency, $version );
117	$this->enqueue_style( $hook );
118	}
119
120	/**
121	* Register a script with prefixed handle.
122	*
123	* @param string $hook Handle suffix.
124	* @param string $path Full URL to the script.
125	* @param array<string> $dependency Script dependencies.
126	* @param string $version Asset version.
127	*
128	* @since 1.0.0
129	* @return void
130	*/
131	public function register_script( $hook, $path, $dependency, $version = ZIPAI_MCP_VERSION ) {
132	// Cache-bust hand-enqueued source scripts on every edit: when the caller
133	// uses the default plugin version, derive a filemtime version from the
134	// on-disk file. In dev this busts the moment a handler changes; in
135	// production it is the build time (stable per deploy). Falls back to the
136	// constant for false/remote/missing sources.
137	if ( ZIPAI_MCP_VERSION === $version && '' !== $path ) {
138	$local = str_replace( ZIPAI_MCP_URL, ZIPAI_MCP_DIR, $path );
139	if ( $local !== $path && file_exists( $local ) ) {
140	$version = (string) filemtime( $local );
141	}
142	}
143	wp_register_script(
144	$this->enqueue_prefix . '-' . $hook,
145	$path,
146	$dependency,
147	$version,
148	true
149	);
150	}
151
152	/**
153	* Enqueue a previously registered script.
154	*
155	* @param string $hook Handle suffix.
156	*
157	* @since 1.0.0
158	* @return void
159	*/
160	public function enqueue_script( $hook ) {
161	wp_enqueue_script( $this->enqueue_prefix . '-' . $hook );
162	}
163
164	/**
165	* Localize a script with prefixed handle and object name.
166	*
167	* @param string $hook Handle suffix.
168	* @param string $object_name JS global object name.
169	* @param array<string, mixed> $data Key-value data to expose.
170	*
171	* @since 1.0.0
172	* @return void
173	*/
174	public function localize_script( $hook, $object_name, $data ) {
175	wp_localize_script(
176	$this->enqueue_prefix . '-' . $hook,
177	$object_name,
178	$data
179	);
180	}
181
182	/**
183	* Register a style with prefixed handle.
184	*
185	* @param string $hook Handle suffix.
186	* @param string $path Full URL to the CSS file.
187	* @param array<string> $dependency Style dependencies.
188	* @param string $version Asset version.
189	*
190	* @since 1.0.0
191	* @return void
192	*/
193	public function register_style( $hook, $path, $dependency = array(), $version = ZIPAI_MCP_VERSION ) {
194	wp_register_style(
195	$this->enqueue_prefix . '-' . $hook,
196	$path,
197	$dependency,
198	$version
199	);
200	}
201
202	/**
203	* Enqueue a previously registered style.
204	*
205	* @param string $hook Handle suffix.
206	*
207	* @since 1.0.0
208	* @return void
209	*/
210	public function enqueue_style( $hook ) {
211	wp_enqueue_style( $this->enqueue_prefix . '-' . $hook );
212	}
213	}
214