fluentcart-developer 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/CLAUDE.md +22 -22
  2. package/LICENSE +21 -21
  3. package/README.md +169 -127
  4. package/SKILL.md +127 -127
  5. package/bin/index.js +281 -281
  6. package/package.json +48 -37
  7. package/skills/fluentcart-developer/SKILL.md +172 -172
  8. package/skills/fluentcart-developer/examples/README.md +25 -25
  9. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  10. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  11. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -114
  12. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -149
  13. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  14. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -62
  15. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -787
  16. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  17. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  18. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  19. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  20. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  21. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  22. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  23. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  24. package/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  25. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -940
  26. package/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  27. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  28. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  29. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -902
  30. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  31. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -1319
  32. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  33. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  34. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  35. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  36. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  37. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  38. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -286
  39. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -794
  40. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  41. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  42. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  43. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  44. package/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  45. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  46. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  47. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -171
  48. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  49. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -1241
  50. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  51. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -2563
  52. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  53. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  54. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  55. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  56. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  57. package/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  58. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -606
  59. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  60. package/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  61. package/skills/fluentcart-developer/scripts/cli.js +1 -1
  62. package/.gitattributes +0 -2
  63. package/CONTRIBUTING.md +0 -73
  64. package/copy-skills.js +0 -43
  65. package/skills.sh.json +0 -13
@@ -1,787 +1,787 @@
1
- # Action Hooks: Admin & Templates
2
-
3
- All hooks related to plugin boot/initialization, admin UI, modules, the block/email editor, form rendering, page templating, shortcode-driven views, policy verification, and custom web routes.
4
-
5
- ---
6
-
7
- ## Boot / Initialization
8
- Fired during plugin startup. These are the earliest FluentCart hooks and let you tap into the container before any other logic runs.
9
-
10
- ### `fluentcart_loaded`
11
- `fluentcart_loaded` — Plugin application container loaded (first hook)
12
-
13
- * **When it runs:** Fires inside the `plugins_loaded` WordPress hook, immediately after the FluentCart Application container is constructed and the Action Scheduler is loaded. This is the very first FluentCart hook — use it to register early bindings, service providers, or listeners before anything else initialises.
14
- * **Source:** `boot/app.php` (line 30)
15
-
16
- #### Parameters:
17
- * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
18
-
19
- #### Usage Example:
20
- ```php
21
- // Hook into plugin application container load (earliest hook)
22
- add_action('fluentcart_loaded', function ($app) {
23
- // Register a custom service into the FluentCart container early
24
- $app->bind('myCustomService', function () {
25
- return new \MyPlugin\CustomService();
26
- });
27
- }, 10, 1);
28
- ```
29
-
30
- ---
31
-
32
- ### `fluent_cart/init`
33
- `fluent_cart/init` — FluentCart fully initialised on WP init
34
-
35
- * **When it runs:** Fires inside the WordPress `init` hook (which itself runs after `plugins_loaded`). By this point, all post types, taxonomies, and rewrite rules are available. Use this for logic that depends on WordPress being fully bootstrapped — custom post type queries, REST route registration, etc.
36
- * **Source:** `boot/app.php` (line 35)
37
-
38
- #### Parameters:
39
- * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
40
-
41
- #### Usage Example:
42
- ```php
43
- // Hook when FluentCart is fully initialised on WP init
44
- add_action('fluent_cart/init', function ($app) {
45
- // Safe to query custom post types or register custom REST routes
46
- register_rest_route('my-plugin/v1', '/data', [
47
- 'methods' => 'GET',
48
- 'callback' => 'my_custom_handler',
49
- ]);
50
- }, 10, 1);
51
- ```
52
-
53
- ---
54
-
55
- ## Admin
56
- Hooks that fire during admin page rendering, menu setup, and asset enqueueing. Use these to extend the FluentCart admin panel.
57
-
58
- ### `admin_menu`
59
- `fluent_cart/admin_menu` — Render admin navigation menu
60
-
61
- * **When it runs:** Fires in two places: inside the admin Vue SPA wrapper (`admin_app.php`) and on the product CPT taxonomy pages. It is the hook that renders the FluentCart admin navigation bar. The default handler (`MenuHandler::renderAdminMenu`) is attached to it to output the menu HTML.
62
- * **Parameters:** None — this is a rendering hook. Callbacks should `echo` HTML.
63
- * **Source:** `app/CPT/FluentProducts.php` (line 333), `app/Views/admin/admin_app.php` (line 4)
64
-
65
- #### Usage Example:
66
- ```php
67
- // Hook to render elements inside FluentCart admin navigation menu
68
- add_action('fluent_cart/admin_menu', function () {
69
- // Append a custom link to the admin navigation bar HTML
70
- echo '<a href="#/my-custom-page" class="fct-nav-item">My Page</a>';
71
- }, 20);
72
- ```
73
-
74
- ---
75
-
76
- ### `admin_submenu_added`
77
- `fluent_cart/admin_submenu_added` — After all admin submenus registered
78
-
79
- * **When it runs:** Fires at the end of `MenuHandler::addAdminMenu()`, after all default submenu items (Dashboard, Orders, Customers, Products, Integrations, Reports, Settings, Coupons, Logs, and taxonomy pages) have been registered under the FluentCart admin menu.
80
- * **Source:** `app/Hooks/Handlers/MenuHandler.php` (line 283)
81
-
82
- #### Parameters:
83
- `$submenu` *(array)*: The WordPress global `$submenu` array (keyed by parent slug). The `fluent-cart` key contains all FluentCart submenu items.
84
-
85
- #### Usage Example:
86
- ```php
87
- // Hook after all default FluentCart admin submenus are registered
88
- add_action('fluent_cart/admin_submenu_added', function ($submenu) {
89
- // Add a custom submenu item programmatically to WordPress global $submenu
90
- global $submenu;
91
- $submenu['fluent-cart']['my_page'] = [
92
- __('My Custom Page', 'my-plugin'),
93
- 'manage_options',
94
- 'admin.php?page=fluent-cart#/my-custom',
95
- ];
96
- }, 10, 1);
97
- ```
98
-
99
- ---
100
-
101
- ### `loading_app`
102
- `fluent_cart/loading_app` — Admin Vue SPA assets about to be enqueued
103
-
104
- * **When it runs:** Fires at the very beginning of `MenuHandler::enqueueAssets()`, before any admin JavaScript or CSS is registered. Use this to enqueue your own scripts or styles that need to load alongside (or before) the admin SPA.
105
- * **Source:** `app/Hooks/Handlers/MenuHandler.php` (line 355)
106
-
107
- #### Parameters:
108
- * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
109
-
110
- #### Usage Example:
111
- ```php
112
- // Hook before FluentCart admin Vue SPA assets are enqueued
113
- add_action('fluent_cart/loading_app', function ($app) {
114
- // Enqueue a custom admin stylesheet before the SPA loads
115
- wp_enqueue_style('my-fct-admin-style', plugins_url('css/admin.css', __FILE__));
116
- }, 10, 1);
117
- ```
118
-
119
- ---
120
-
121
- ### `admin_js_loaded`
122
- `fluent_cart/admin_js_loaded` — After all admin JS enqueued and localised
123
-
124
- * **When it runs:** Fires at the end of `MenuHandler::enqueueAssets()`, after all admin scripts have been enqueued and `wp_localize_script` has injected the `fluentCartAdminApp` and `fluentCartRestVars` objects. Use this to enqueue scripts that depend on the admin SPA data being available, or to add inline script data.
125
- * **Source:** `app/Hooks/Handlers/MenuHandler.php` (line 465)
126
-
127
- #### Parameters:
128
- * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
129
-
130
- #### Usage Example:
131
- ```php
132
- // Hook after all admin JS is enqueued and localized
133
- add_action('fluent_cart/admin_js_loaded', function ($app) {
134
- // Enqueue a script that depends on the admin app being fully loaded
135
- wp_enqueue_script('my-fct-addon', plugins_url('js/addon.js', __FILE__), [], '1.0', true);
136
-
137
- // Add inline data that references fluentCartAdminApp
138
- wp_add_inline_script('my-fct-addon', 'window.myAddonConfig = { ready: true };', 'before');
139
- }, 10, 1);
140
- ```
141
-
142
- ---
143
-
144
- ## Modules
145
- Hooks that fire when built-in FluentCart modules (e.g. stock management, subscriptions, shipping) are activated or deactivated via the admin settings panel.
146
-
147
- ### `module/deactivated/{module_key}`
148
- `fluent_cart/module/deactivated/{$moduleKey}` — Module deactivated (dynamic)
149
-
150
- * **When it runs:** Fires inside `ModuleSettingsController::saveSettings()` when a module's active status transitions from `'yes'` to `'no'`. The `{$moduleKey}` portion is replaced dynamically with the module identifier.
151
- * **Available dynamic variants:** `stock_management`, `subscriptions`, `shipping`, `tax`, `coupon`, `license`, `digital_downloads`, and any other registered module key.
152
- * **Source:** `app/Http/Controllers/ModuleSettingsController.php` (line 58)
153
-
154
- #### Parameters:
155
- * `$moduleData` *(array)* — The newly saved settings for this module (`['active' => 'no', ...]`)
156
- * `$prevModuleData` *(array)* — The previous settings for this module before the save (`['active' => 'yes', ...]`)
157
-
158
- #### Usage Example:
159
- ```php
160
- // Hook when stock management module is deactivated
161
- add_action('fluent_cart/module/deactivated/stock_management', function ($moduleData, $prevModuleData) {
162
- // Clean up stock-related cron jobs when stock management is turned off
163
- as_unschedule_all_actions('fluent_cart/stock_check');
164
- }, 10, 2);
165
- ```
166
-
167
- ---
168
-
169
- ### `module/activated/{module_key}`
170
- `fluent_cart/module/activated/{$moduleKey}` — Module activated (dynamic)
171
-
172
- * **When it runs:** Fires inside `ModuleSettingsController::saveSettings()` when a module's active status transitions from `'no'` to `'yes'`. The `{$moduleKey}` portion is replaced dynamically with the module identifier.
173
- * **Available dynamic variants:** `stock_management`, `subscriptions`, `shipping`, `tax`, `coupon`, `license`, `digital_downloads`, and any other registered module key.
174
- * **Source:** `app/Http/Controllers/ModuleSettingsController.php` (line 61)
175
-
176
- #### Parameters:
177
- * `$moduleData` *(array)* — The newly saved settings for this module (`['active' => 'yes', ...]`)
178
- * `$prevModuleData` *(array)* — The previous settings for this module before the save (`['active' => 'no', ...]`)
179
-
180
- #### Usage Example:
181
- ```php
182
- // Hook when subscriptions module is activated
183
- add_action('fluent_cart/module/activated/subscriptions', function ($moduleData, $prevModuleData) {
184
- // Run database migrations when subscriptions module is first activated
185
- \FluentCart\Database\DBMigrator::run('subscription_tables');
186
- }, 10, 2);
187
- ```
188
-
189
- ---
190
-
191
- ## Block Editor / Email Editor
192
- Hooks for the custom FluentCart block editor used to compose email templates. These fire during the editor page lifecycle and asset loading.
193
-
194
- ### `fluent_cart_enqueue_block_editor_assets`
195
- `fluent_cart_enqueue_block_editor_assets` — Block editor assets being enqueued
196
-
197
- * **When it runs:** Fires at the end of `FluentCartBlockEditorHandler::enqueueEditorStyles()`, after all core WordPress block editor styles (`wp-edit-post`, `wp-block-library`, etc.) have been enqueued. WordPress's own `wp_enqueue_editor_format_library_assets` is also attached to this hook. Use it to add custom styles or scripts to the email block editor.
198
- * **Parameters:** None.
199
- * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 428)
200
-
201
- #### Usage Example:
202
- ```php
203
- // Hook when email block editor assets are enqueued
204
- add_action('fluent_cart_enqueue_block_editor_assets', function () {
205
- // Add custom styles for the email block editor page
206
- wp_enqueue_style('my-email-editor-styles', plugins_url('css/email-editor.css', __FILE__));
207
- }, 10);
208
- ```
209
-
210
- ---
211
-
212
- ### `fluent_cart_block_editor/head`
213
- `fluent_cart_block_editor/head` — In `<head>` of custom block editor page
214
-
215
- * **When it runs:** Fires inside the `<head>` tag of the custom block editor HTML page. WordPress core hooks (`wp_enqueue_scripts`, `wp_print_styles`, `wp_print_head_scripts`, etc.) are pre-attached to this action so that editor stylesheets and scripts are output in the correct location. Use this to inject additional `<meta>`, `<link>`, or `<style>` tags into the editor page head.
216
- * **Parameters:** None.
217
- * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 620)
218
-
219
- #### Usage Example:
220
- ```php
221
- // Hook inside head tag of custom block editor page
222
- add_action('fluent_cart_block_editor/head', function () {
223
- // Inject a custom Google font stylesheet link into the editor head
224
- echo '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap">';
225
- }, 20);
226
- ```
227
-
228
- ---
229
-
230
- ### `block_editor_head`
231
- `fluent_cart/block_editor_head` — Second head hook in block editor page
232
-
233
- * **When it runs:** Fires immediately after `fluent_cart_block_editor/head` inside the `<head>` tag, right before the closing `</head>`. This is a secondary head hook — use it for last-minute style overrides or scripts that must load after everything else in the head.
234
- * **Parameters:** None.
235
- * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 622)
236
-
237
- #### Usage Example:
238
- ```php
239
- // Secondary head hook right before closing head tag in block editor
240
- add_action('fluent_cart/block_editor_head', function () {
241
- // Override editor font family styles as final head injection
242
- echo '<style>.editor-styles-wrapper { font-family: "Inter", sans-serif; }</style>';
243
- }, 10);
244
- ```
245
-
246
- ---
247
-
248
- ### `new_block_editor_footer`
249
- `fluent_cart/new_block_editor_footer` — Footer of custom block editor page (for JS)
250
-
251
- * **When it runs:** Fires inside the `<body>` of the custom block editor page, after the editor `<div>` and before `</body>`. This is the recommended place to inject footer JavaScript for the email editor.
252
- * **Parameters:** None.
253
- * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 629)
254
-
255
- #### Usage Example:
256
- ```php
257
- // Hook inside body of custom block editor page before closing body tag
258
- add_action('fluent_cart/new_block_editor_footer', function () {
259
- // Inject custom JavaScript into email editor page footer
260
- echo '<script>console.log("FluentCart email editor loaded");</script>';
261
- }, 10);
262
- ```
263
-
264
- ---
265
-
266
- ### `block_editor/enqueue_assets`
267
- `fluent_cart/block_editor/enqueue_assets` — After email editor block assets enqueued
268
-
269
- * **When it runs:** Fires at the end of `FluentCartBlockEditorHandler::enqueueEmailEditorBlocks()`, after all FluentCart-specific email editor block scripts, styles, and global editor SCSS have been enqueued. Use this to register additional custom blocks or scripts for the email editor.
270
- * **Parameters:** None.
271
- * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 1232)
272
-
273
- #### Usage Example:
274
- ```php
275
- // Hook after email editor block scripts and styles are enqueued
276
- add_action('fluent_cart/block_editor/enqueue_assets', function () {
277
- // Register custom email block script for editor
278
- wp_enqueue_script('my-email-block', plugins_url('js/my-email-block.js', __FILE__), ['wp-blocks'], '1.0', true);
279
- }, 10);
280
- ```
281
-
282
- ---
283
-
284
- ### `block_editor/render_block`
285
- `fluent_cart/block_editor/render_block` — Render unknown block types in email parser
286
-
287
- * **When it runs:** Fires inside `FluentBlockParser` when processing a block whose name is not recognised by any built-in handler and is not a standard email editor block. The hook runs inside `ob_start()` — any output you echo will be captured and used as the block's rendered HTML in the email. If nothing is output, the parser falls back to raw innerHTML.
288
- * **Source:** `app/Services/Email/FluentBlockParser.php` (line 278)
289
-
290
- #### Parameters:
291
- `$data` *(array)*: Block rendering context
292
- ```php
293
- $data = [
294
- 'block' => [...], // array — Full block array (name, attrs, innerBlocks, innerHTML, etc.)
295
- 'block_name' => 'my/custom', // string — The block type name string
296
- 'attributes' => [...], // array — Block attributes array
297
- ];
298
- ```
299
-
300
- #### Usage Example:
301
- ```php
302
- // Hook to render unrecognized block types in email parser
303
- add_action('fluent_cart/block_editor/render_block', function ($data) {
304
- // Check block type name match
305
- if ($data['block_name'] === 'my-plugin/promo-banner') {
306
- $heading = $data['attributes']['heading'] ?? 'Special Offer';
307
- // Echo rendered HTML for custom promo banner block
308
- echo '<div style="background: #f0f0f0; padding: 20px; text-align: center;">';
309
- echo '<h2>' . esc_html($heading) . '</h2>';
310
- echo '</div>';
311
- }
312
- }, 10, 1);
313
- ```
314
-
315
- ---
316
-
317
- ## Form Rendering
318
-
319
- ### `render_custom_form_field`
320
- `fluent_cart/render_custom_form_field` — Unrecognised form field type fallback
321
-
322
- * **When it runs:** Fires inside the `default` case of `FormFieldRenderer::renderField()` when the field type does not match any built-in type (`section`, `sub_section`, `text`, `email`, `tel`, `number`, `textarea`, `checkbox`, `select`, `address_select`). Use this to render custom field types in the checkout or registration forms.
323
- * **Source:** `app/Services/Renderer/FormFieldRenderer.php` (line 58)
324
-
325
- #### Parameters:
326
- `$fieldData` *(array)*: The field configuration array
327
- ```php
328
- $fieldData = [
329
- 'type' => 'my_custom_type', // string — The unrecognised field type
330
- 'label' => 'Custom Field', // string — Field label
331
- 'id' => 'my_field', // string — Field HTML ID
332
- 'name' => 'my_field', // string — Field name attribute
333
- 'required' => true, // bool — Whether the field is required
334
- 'wrapper_class' => '', // string — CSS class for the wrapper
335
- 'options' => [], // array — Options (if applicable)
336
- ];
337
- ```
338
-
339
- #### Usage Example:
340
- ```php
341
- // Hook to render unrecognized form field types in checkout
342
- add_action('fluent_cart/render_custom_form_field', function ($fieldData) {
343
- // Render custom date_picker field type HTML
344
- if ($fieldData['type'] === 'date_picker') {
345
- $id = esc_attr($fieldData['id'] ?? '');
346
- $name = esc_attr($fieldData['name'] ?? '');
347
- $label = esc_html($fieldData['label'] ?? '');
348
- $required = !empty($fieldData['required']) ? 'required' : '';
349
- echo "<div class='fct_form_field'>";
350
- echo "<label for='{$id}'>{$label}</label>";
351
- echo "<input type='date' id='{$id}' name='{$name}' {$required} />";
352
- echo "</div>";
353
- }
354
- }, 10, 1);
355
- ```
356
-
357
- ---
358
-
359
- ## Templating
360
- Hooks for the generic fallback template used on product archive pages and other FluentCart template-driven pages. They fire in sequence from top to bottom of the page layout.
361
-
362
- ### `generic_template/rendering`
363
- `fluent_cart/generic_template/rendering` — Start of generic fallback template
364
-
365
- * **When it runs:** Fires at the very top of `fallback-generic-template.php`, before `get_header()` is called. Use this to set up global variables, enqueue assets, or modify the page state before any template output begins.
366
- * **Parameters:** None.
367
- * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 7)
368
-
369
- #### Usage Example:
370
- ```php
371
- // Hook at top of generic fallback template before get_header()
372
- add_action('fluent_cart/generic_template/rendering', function () {
373
- // Enqueue custom styles for product archive template
374
- wp_enqueue_style('my-archive-styles', plugins_url('css/archive.css', __FILE__));
375
- }, 10);
376
- ```
377
-
378
- ---
379
-
380
- ### `generic_template/before_content`
381
- `fluent_cart/generic_template/before_content` — After get_header(), before main wrapper
382
-
383
- * **When it runs:** Fires after the WordPress header has been rendered by `get_header()` and before the main content wrapper `<div>` opens. Use this for banners, breadcrumbs, or other full-width elements above the content area.
384
- * **Parameters:** None.
385
- * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 10)
386
-
387
- #### Usage Example:
388
- ```php
389
- // Hook after get_header() and before main wrapper in generic template
390
- add_action('fluent_cart/generic_template/before_content', function () {
391
- // Add breadcrumb trail above product archive
392
- echo '<nav class="fct-breadcrumb">Home &raquo; Shop</nav>';
393
- }, 10);
394
- ```
395
-
396
- ---
397
-
398
- ### `template/before_content`
399
- `fluent_cart/template/before_content` — Inside main wrapper, before content
400
-
401
- * **When it runs:** Fires inside the `<div id="main">` site-main wrapper, before the main content hook. Use this for content-width elements like filter bars or category headers that sit above the product grid.
402
- * **Parameters:** None.
403
- * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 13)
404
-
405
- #### Usage Example:
406
- ```php
407
- // Hook inside main wrapper before main content area
408
- add_action('fluent_cart/template/before_content', function () {
409
- // Show category filter bar above product grid
410
- echo '<div class="fct-filter-bar">Filter by category...</div>';
411
- }, 10);
412
- ```
413
-
414
- ---
415
-
416
- ### `template/main_content`
417
- `fluent_cart/template/main_content` — Main content area
418
-
419
- * **When it runs:** Fires inside the `<div id="main">` wrapper between the `before_content` and `after_content` hooks. This is where the primary page content (product grid, archive loop, etc.) is rendered. FluentCart's templating module hooks its archive rendering here.
420
- * **Parameters:** None.
421
- * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 14)
422
-
423
- #### Usage Example:
424
- ```php
425
- // Hook inside main wrapper to render primary page content
426
- add_action('fluent_cart/template/main_content', function () {
427
- // Output custom product grid layout HTML
428
- echo '<div class="my-custom-product-grid">Custom grid here</div>';
429
- }, 10);
430
- ```
431
-
432
- ---
433
-
434
- ### `template/after_content`
435
- `fluent_cart/template/after_content` — After main content
436
-
437
- * **When it runs:** Fires inside the `<div id="main">` wrapper after the main content has been rendered. Use this for pagination, call-to-action blocks, or related products sections that sit below the product grid.
438
- * **Parameters:** None.
439
- * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 15)
440
-
441
- #### Usage Example:
442
- ```php
443
- // Hook inside main wrapper after primary page content
444
- add_action('fluent_cart/template/after_content', function () {
445
- // Render pagination elements below product grid
446
- echo '<div class="fct-pagination"><!-- pagination links --></div>';
447
- }, 10);
448
- ```
449
-
450
- ---
451
-
452
- ### `generic_template/after_content`
453
- `fluent_cart/generic_template/after_content` — After main wrapper, before get_footer()
454
-
455
- * **When it runs:** Fires after the main content wrapper `<div>` closes and before `get_footer()` renders the site footer. Use this for full-width elements below the content area like newsletter signups or related content.
456
- * **Parameters:** None.
457
- * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 18)
458
-
459
- #### Usage Example:
460
- ```php
461
- // Hook after main wrapper closes and before get_footer()
462
- add_action('fluent_cart/generic_template/after_content', function () {
463
- // Output full-width newsletter signup section
464
- echo '<section class="fct-newsletter">Subscribe to our newsletter</section>';
465
- }, 10);
466
- ```
467
-
468
- ---
469
-
470
- ## Views (Shortcode-Driven Rendering)
471
- Hooks that render specific view partials on the checkout page, receipt emails, and customer-facing forms. These fire inside `ob_start()` / `ob_get_clean()` blocks — your callbacks should `echo` HTML output.
472
-
473
- ### `views/checkout_page_cart_item_list`
474
- `fluent_cart/views/checkout_page_cart_item_list` — Render cart item list on checkout
475
-
476
- * **When it runs:** Fires inside `CheckoutController::getCheckoutSummary()` to render the cart item list partial on the checkout page. The output is captured via `ob_start()` and returned as part of the checkout summary AJAX response.
477
- * **Source:** `app/Http/Controllers/CheckoutController.php` (line 39)
478
-
479
- #### Parameters:
480
- `$data` *(array)*: Checkout context
481
- ```php
482
- $data = [
483
- 'checkout' => $checkOutHelper, // \FluentCart\App\Helpers\CartCheckoutHelper instance
484
- 'items' => [...], // array — Cart items from $checkOutHelper->getItems()
485
- ];
486
- ```
487
-
488
- #### Usage Example:
489
- ```php
490
- // Hook to render cart item list partial on checkout page
491
- add_action('fluent_cart/views/checkout_page_cart_item_list', function ($data) {
492
- // Extract items array from checkout data
493
- $items = $data['items'];
494
- echo '<div class="fct-cart-items">';
495
- foreach ($items as $item) {
496
- echo '<div class="fct-cart-item">' . esc_html($item['title'] ?? '') . '</div>';
497
- }
498
- echo '</div>';
499
- }, 10, 1);
500
- ```
501
-
502
- ---
503
-
504
- ### `views/checkout_page_registration_form`
505
- `fluent_cart/views/checkout_page_registration_form` — Render registration form on checkout
506
-
507
- * **When it runs:** Fires inside `CustomerRegistrationHandler::render()` to output the guest registration form on the checkout page. The output is captured via `ob_start()` and returned as the rendered form HTML.
508
- * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerRegistrationHandler.php` (line 79)
509
-
510
- #### Parameters:
511
- `$viewData` *(array)*: View context
512
- ```php
513
- $viewData = [
514
- 'checkout' => $checkOutHelper, // \FluentCart\App\Helpers\CartCheckoutHelper instance
515
- ];
516
- ```
517
-
518
- #### Usage Example:
519
- ```php
520
- // Hook to render guest registration form on checkout page
521
- add_action('fluent_cart/views/checkout_page_registration_form', function ($viewData) {
522
- // Extract checkout helper instance
523
- $checkout = $viewData['checkout'];
524
- echo '<div class="fct-registration-form">';
525
- echo '<h3>Create an Account</h3>';
526
- // Render custom registration input fields
527
- echo '<input type="text" name="full_name" placeholder="Full Name" />';
528
- echo '<input type="email" name="email" placeholder="Email" />';
529
- echo '<input type="password" name="password" placeholder="Password" />';
530
- echo '</div>';
531
- }, 10, 1);
532
- ```
533
-
534
- ---
535
-
536
- ### `views/checkout_page_login_form`
537
- `fluent_cart/views/checkout_page_login_form` — Render login form on checkout
538
-
539
- * **When it runs:** Fires inside `CustomerLoginHandler::render()` to output the login form on the checkout page for returning customers. The output is captured via `ob_start()` and returned as the rendered form HTML.
540
- * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerLoginHandler.php` (line 81)
541
-
542
- #### Parameters:
543
- `$viewData` *(array)*: View context (same structure as `registration_form`)
544
-
545
- #### Usage Example:
546
- ```php
547
- // Hook to render returning customer login form on checkout page
548
- add_action('fluent_cart/views/checkout_page_login_form', function ($viewData) {
549
- // Render login form inputs and submit button
550
- echo '<div class="fct-login-form">';
551
- echo '<h3>Returning Customer? Log In</h3>';
552
- echo '<input type="email" name="email" placeholder="Email" />';
553
- echo '<input type="password" name="password" placeholder="Password" />';
554
- echo '<button type="submit">Log In</button>';
555
- echo '</div>';
556
- }, 10, 1);
557
- ```
558
-
559
- ---
560
-
561
- ### `views/checkout_order_summary`
562
- `fluent_cart/views/checkout_order_summary` — Render order summary (email shortcodes)
563
-
564
- * **When it runs:** Fires inside `ShortcodeParser::getSummary()` when the shortcode is parsed in email templates. The output is captured via `ob_start()` and inserted into the email body as the order summary block. Receives the Order model instance.
565
- * **Source:** `app/Services/ShortCodeParser/ShortcodeParser.php` (line 248)
566
-
567
- #### Parameters:
568
- `$data` *(array)*: Order summary context
569
- ```php
570
- $data = [
571
- 'order' => $order, // \FluentCart\App\Models\Order instance
572
- 'paymentReceipt' => $paymentReceipt, // \FluentCart\App\Services\PaymentReceipt instance
573
- ];
574
- ```
575
-
576
- #### Usage Example:
577
- ```php
578
- // Hook to render order summary block in email shortcodes
579
- add_action('fluent_cart/views/checkout_order_summary', function ($data) {
580
- // Extract order model and payment receipt instances
581
- $order = $data['order'];
582
- $receipt = $data['paymentReceipt'];
583
- echo '<table class="fct-order-summary">';
584
- echo '<tr><th>Order #' . esc_html($order->id) . '</th></tr>';
585
- // Render order summary table rows
586
- echo '</table>';
587
- }, 10, 1);
588
- ```
589
-
590
- ---
591
-
592
- ### `views/checkout_order_receipt`
593
- `fluent_cart/views/checkout_order_receipt` — Render full order receipt (email shortcodes)
594
-
595
- * **When it runs:** Fires inside `ShortcodeParser::getReceipt()` when the shortcode is parsed in email templates. The output is captured via `ob_start()` and inserted into the email body as the complete Order receipt.
596
- * **Source:** `app/Services/ShortCodeParser/ShortcodeParser.php` (line 256)
597
-
598
- #### Parameters:
599
- `$data` *(array)*: Order receipt context (same structure as `checkout_order_summary`)
600
-
601
- #### Usage Example:
602
- ```php
603
- // Hook to render full order receipt block in email shortcodes
604
- add_action('fluent_cart/views/checkout_order_receipt', function ($data) {
605
- // Extract order model and payment receipt instances
606
- $order = $data['order'];
607
- $receipt = $data['paymentReceipt'];
608
- echo '<div class="fct-receipt">';
609
- echo '<h2>Receipt for Order #' . esc_html($order->id) . '</h2>';
610
- // Render full receipt wrapper HTML
611
- echo '</div>';
612
- }, 10, 1);
613
- ```
614
-
615
- ---
616
-
617
- ### `views/checkout_page_shipping_method_list`
618
- `fluent_cart/views/checkout_page_shipping_method_list` — Render shipping method list
619
-
620
- * **When it runs:** Fires inside `ShippingFrontendController::getShippingMethodsListView()` to render the list of available `ShippingMethod` instances on the checkout page. The output is captured via `ob_start()` and returned as part of the shipping methods AJAX response.
621
- * **Source:** `app/Modules/Shipping/Http/Controllers/Frontend/ShippingFrontendController.php` (line 75)
622
-
623
- #### Parameters:
624
- `$data` *(array)*: Shipping methods context
625
- ```php
626
- $data = [
627
- 'shipping_methods' => [
628
- // Array of available \FluentCart\App\Models\ShippingMethod instances filtered by country
629
- ],
630
- ];
631
- ```
632
-
633
- #### Usage Example:
634
- ```php
635
- // Hook to render shipping method list partial on checkout page
636
- add_action('fluent_cart/views/checkout_page_shipping_method_list', function ($data) {
637
- // Extract filtered shipping methods list array
638
- $methods = $data['shipping_methods'];
639
- echo '<div class="fct-shipping-methods">';
640
- foreach ($methods as $method) {
641
- echo '<label>';
642
- echo '<input type="radio" name="shipping_method" value="' . esc_attr($method->id) . '" />';
643
- echo esc_html($method->title);
644
- echo '</label>';
645
- }
646
- echo '</div>';
647
- }, 10, 1);
648
- ```
649
-
650
- ---
651
-
652
- ### `views/checkout_page_form_address_info_wrapper`
653
- `fluent_cart/views/checkout_page_form_address_info_wrapper` — Render address info card
654
-
655
- * **When it runs:** Fires inside `CustomerController` when rendering the address information card on the checkout page after a customer selects or submits their address. The output is captured via `ob_start()` and returned in the AJAX response.
656
- * **Source:** `app/Http/Controllers/FrontendControllers/CustomerController.php` (line 137)
657
-
658
- #### Parameters:
659
- `$data` *(array)*: Address display data
660
- ```php
661
- $data = [
662
- 'name' => 'John Doe', // string — Customer name
663
- 'phone' => '+1234567890', // string — Customer phone number
664
- 'label' => 'Home', // string — Address label
665
- 'address' => '123 Main St, City, State, Country', // string — Formatted address string
666
- ];
667
- ```
668
-
669
- #### Usage Example:
670
- ```php
671
- // Hook to render address info card view on checkout page
672
- add_action('fluent_cart/views/checkout_page_form_address_info_wrapper', function ($data) {
673
- // Render formatted address info card block
674
- echo '<div class="fct-address-card">';
675
- echo '<strong>' . esc_html($data['name']) . '</strong>';
676
- if (!empty($data['phone'])) {
677
- echo '<br />' . esc_html($data['phone']);
678
- }
679
- echo '<br />' . esc_html($data['address']);
680
- echo '</div>';
681
- }, 10, 1);
682
- ```
683
-
684
- ---
685
-
686
- ## Policies / Security
687
- Hooks that fire during REST API policy verification. These allow you to add custom security checks, rate limiting, or audit logging before the standard permission check runs.
688
-
689
- ### `policy/store_sensitive_request`
690
- `fluent_cart/policy/store_sensitive_request` — Store-sensitive API request verification
691
-
692
- * **When it runs:** Fires at the beginning of `StoreSensitivePolicy::verifyRequest()`, before the `store/sensitive` capability check is performed. This policy protects sensitive store operations (e.g. payment gateway configuration, API key management). Use this to add additional security measures like IP whitelisting or two-factor verification.
693
- * **Source:** `app/Http/Policies/StoreSensitivePolicy.php` (line 11)
694
-
695
- #### Parameters:
696
- `$data` *(array)*: Request context
697
- ```php
698
- $data = [
699
- 'request' => $request, // \FluentCart\Framework\Http\Request\Request instance
700
- ];
701
- ```
702
-
703
- #### Usage Example:
704
- ```php
705
- // Hook before store-sensitive REST API capability check is performed
706
- add_action('fluent_cart/policy/store_sensitive_request', function ($data) {
707
- // Extract request object and remote IP address
708
- $request = $data['request'];
709
- $ip = $request->server('REMOTE_ADDR');
710
-
711
- // Log sensitive API access attempt details
712
- fluent_cart_add_log(
713
- 'Sensitive API Access',
714
- sprintf('IP: %s, Endpoint: %s', $ip, $request->url()),
715
- 'info'
716
- );
717
- }, 10, 1);
718
- ```
719
-
720
- ---
721
-
722
- ### `policy/store_settings_request`
723
- `fluent_cart/policy/store_settings_request` — Store-settings API request verification
724
-
725
- * **When it runs:** Fires at the beginning of `StoreSettingsPolicy::verifyRequest()`, before the route-meta permission check (`hasRoutePermissions()`) is performed. This policy protects store settings endpoints (e.g. general settings, email templates, checkout configuration). Use this for additional validation or logging.
726
- * **Source:** `app/Http/Policies/StoreSettingsPolicy.php` (line 11)
727
-
728
- #### Parameters:
729
- `$data` *(array)*: Request context (same structure as `store_sensitive_request`)
730
-
731
- #### Usage Example:
732
- ```php
733
- // Hook before store-settings REST API capability check is performed
734
- add_action('fluent_cart/policy/store_settings_request', function ($data) {
735
- // Extract request object
736
- $request = $data['request'];
737
-
738
- // Restrict settings changes to specific allowed admin user IDs
739
- $allowedUserIds = [1, 2, 3];
740
- if (!in_array(get_current_user_id(), $allowedUserIds)) {
741
- wp_die('You are not allowed to modify store settings.', 403);
742
- }
743
- }, 10, 1);
744
- ```
745
-
746
- ---
747
-
748
- ## Web Routes
749
- Dynamic hooks for custom web route endpoints. Used primarily by payment gateways for IPN (Instant Payment Notification) callbacks, webhook handlers, and other server-to-server endpoints.
750
-
751
- ### `fluent_cart_action_{page}`
752
- `fluent_cart_action_{$page}` — Custom web route action handler (dynamic)
753
-
754
- * **When it runs:** Fires inside `WebRoutes` when the current FluentCart web route `$page` slug matches a registered action. After the action fires, `die()` is called immediately — your callback must handle the full response (headers, body, exit). This is typically used by payment gateway modules to register IPN/webhook listeners (e.g. `fluent_cart_action_stripe_ipn`).
755
- * **Source:** `app/Http/Routes/WebRoutes.php` (line 198)
756
-
757
- #### Parameters:
758
- `$requestData` *(array)*: All request parameters from `App::request()->all()`, which includes merged GET and POST data.
759
- ```php
760
- $requestData = [
761
- 'webhook_id' => 'evt_123abc',
762
- 'payment_type' => 'subscription',
763
- // ... any other query string and POST body parameters
764
- ];
765
- ```
766
-
767
- #### Usage Example:
768
- ```php
769
- // Hook for custom web route IPN callback action handler
770
- add_action('fluent_cart_action_my_gateway_ipn', function ($requestData) {
771
- // Verify incoming HTTP webhook payload and signature
772
- $payload = file_get_contents('php://input');
773
- $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
774
-
775
- if (!verify_webhook_signature($payload, $signature)) {
776
- status_header(403);
777
- echo 'Invalid signature';
778
- return;
779
- }
780
-
781
- // Process IPN payment notification payload
782
- process_ipn_notification($requestData);
783
-
784
- status_header(200);
785
- echo 'OK';
786
- }, 10, 1);
787
- ```
1
+ # Action Hooks: Admin & Templates
2
+
3
+ All hooks related to plugin boot/initialization, admin UI, modules, the block/email editor, form rendering, page templating, shortcode-driven views, policy verification, and custom web routes.
4
+
5
+ ---
6
+
7
+ ## Boot / Initialization
8
+ Fired during plugin startup. These are the earliest FluentCart hooks and let you tap into the container before any other logic runs.
9
+
10
+ ### `fluentcart_loaded`
11
+ `fluentcart_loaded` — Plugin application container loaded (first hook)
12
+
13
+ * **When it runs:** Fires inside the `plugins_loaded` WordPress hook, immediately after the FluentCart Application container is constructed and the Action Scheduler is loaded. This is the very first FluentCart hook — use it to register early bindings, service providers, or listeners before anything else initialises.
14
+ * **Source:** `boot/app.php` (line 30)
15
+
16
+ #### Parameters:
17
+ * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
18
+
19
+ #### Usage Example:
20
+ ```php
21
+ // Hook into plugin application container load (earliest hook)
22
+ add_action('fluentcart_loaded', function ($app) {
23
+ // Register a custom service into the FluentCart container early
24
+ $app->bind('myCustomService', function () {
25
+ return new \MyPlugin\CustomService();
26
+ });
27
+ }, 10, 1);
28
+ ```
29
+
30
+ ---
31
+
32
+ ### `fluent_cart/init`
33
+ `fluent_cart/init` — FluentCart fully initialised on WP init
34
+
35
+ * **When it runs:** Fires inside the WordPress `init` hook (which itself runs after `plugins_loaded`). By this point, all post types, taxonomies, and rewrite rules are available. Use this for logic that depends on WordPress being fully bootstrapped — custom post type queries, REST route registration, etc.
36
+ * **Source:** `boot/app.php` (line 35)
37
+
38
+ #### Parameters:
39
+ * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
40
+
41
+ #### Usage Example:
42
+ ```php
43
+ // Hook when FluentCart is fully initialised on WP init
44
+ add_action('fluent_cart/init', function ($app) {
45
+ // Safe to query custom post types or register custom REST routes
46
+ register_rest_route('my-plugin/v1', '/data', [
47
+ 'methods' => 'GET',
48
+ 'callback' => 'my_custom_handler',
49
+ ]);
50
+ }, 10, 1);
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Admin
56
+ Hooks that fire during admin page rendering, menu setup, and asset enqueueing. Use these to extend the FluentCart admin panel.
57
+
58
+ ### `admin_menu`
59
+ `fluent_cart/admin_menu` — Render admin navigation menu
60
+
61
+ * **When it runs:** Fires in two places: inside the admin Vue SPA wrapper (`admin_app.php`) and on the product CPT taxonomy pages. It is the hook that renders the FluentCart admin navigation bar. The default handler (`MenuHandler::renderAdminMenu`) is attached to it to output the menu HTML.
62
+ * **Parameters:** None — this is a rendering hook. Callbacks should `echo` HTML.
63
+ * **Source:** `app/CPT/FluentProducts.php` (line 333), `app/Views/admin/admin_app.php` (line 4)
64
+
65
+ #### Usage Example:
66
+ ```php
67
+ // Hook to render elements inside FluentCart admin navigation menu
68
+ add_action('fluent_cart/admin_menu', function () {
69
+ // Append a custom link to the admin navigation bar HTML
70
+ echo '<a href="#/my-custom-page" class="fct-nav-item">My Page</a>';
71
+ }, 20);
72
+ ```
73
+
74
+ ---
75
+
76
+ ### `admin_submenu_added`
77
+ `fluent_cart/admin_submenu_added` — After all admin submenus registered
78
+
79
+ * **When it runs:** Fires at the end of `MenuHandler::addAdminMenu()`, after all default submenu items (Dashboard, Orders, Customers, Products, Integrations, Reports, Settings, Coupons, Logs, and taxonomy pages) have been registered under the FluentCart admin menu.
80
+ * **Source:** `app/Hooks/Handlers/MenuHandler.php` (line 283)
81
+
82
+ #### Parameters:
83
+ `$submenu` *(array)*: The WordPress global `$submenu` array (keyed by parent slug). The `fluent-cart` key contains all FluentCart submenu items.
84
+
85
+ #### Usage Example:
86
+ ```php
87
+ // Hook after all default FluentCart admin submenus are registered
88
+ add_action('fluent_cart/admin_submenu_added', function ($submenu) {
89
+ // Add a custom submenu item programmatically to WordPress global $submenu
90
+ global $submenu;
91
+ $submenu['fluent-cart']['my_page'] = [
92
+ __('My Custom Page', 'my-plugin'),
93
+ 'manage_options',
94
+ 'admin.php?page=fluent-cart#/my-custom',
95
+ ];
96
+ }, 10, 1);
97
+ ```
98
+
99
+ ---
100
+
101
+ ### `loading_app`
102
+ `fluent_cart/loading_app` — Admin Vue SPA assets about to be enqueued
103
+
104
+ * **When it runs:** Fires at the very beginning of `MenuHandler::enqueueAssets()`, before any admin JavaScript or CSS is registered. Use this to enqueue your own scripts or styles that need to load alongside (or before) the admin SPA.
105
+ * **Source:** `app/Hooks/Handlers/MenuHandler.php` (line 355)
106
+
107
+ #### Parameters:
108
+ * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
109
+
110
+ #### Usage Example:
111
+ ```php
112
+ // Hook before FluentCart admin Vue SPA assets are enqueued
113
+ add_action('fluent_cart/loading_app', function ($app) {
114
+ // Enqueue a custom admin stylesheet before the SPA loads
115
+ wp_enqueue_style('my-fct-admin-style', plugins_url('css/admin.css', __FILE__));
116
+ }, 10, 1);
117
+ ```
118
+
119
+ ---
120
+
121
+ ### `admin_js_loaded`
122
+ `fluent_cart/admin_js_loaded` — After all admin JS enqueued and localised
123
+
124
+ * **When it runs:** Fires at the end of `MenuHandler::enqueueAssets()`, after all admin scripts have been enqueued and `wp_localize_script` has injected the `fluentCartAdminApp` and `fluentCartRestVars` objects. Use this to enqueue scripts that depend on the admin SPA data being available, or to add inline script data.
125
+ * **Source:** `app/Hooks/Handlers/MenuHandler.php` (line 465)
126
+
127
+ #### Parameters:
128
+ * `$app` *(\FluentCart\Framework\Foundation\Application)* — The FluentCart application container instance
129
+
130
+ #### Usage Example:
131
+ ```php
132
+ // Hook after all admin JS is enqueued and localized
133
+ add_action('fluent_cart/admin_js_loaded', function ($app) {
134
+ // Enqueue a script that depends on the admin app being fully loaded
135
+ wp_enqueue_script('my-fct-addon', plugins_url('js/addon.js', __FILE__), [], '1.0', true);
136
+
137
+ // Add inline data that references fluentCartAdminApp
138
+ wp_add_inline_script('my-fct-addon', 'window.myAddonConfig = { ready: true };', 'before');
139
+ }, 10, 1);
140
+ ```
141
+
142
+ ---
143
+
144
+ ## Modules
145
+ Hooks that fire when built-in FluentCart modules (e.g. stock management, subscriptions, shipping) are activated or deactivated via the admin settings panel.
146
+
147
+ ### `module/deactivated/{module_key}`
148
+ `fluent_cart/module/deactivated/{$moduleKey}` — Module deactivated (dynamic)
149
+
150
+ * **When it runs:** Fires inside `ModuleSettingsController::saveSettings()` when a module's active status transitions from `'yes'` to `'no'`. The `{$moduleKey}` portion is replaced dynamically with the module identifier.
151
+ * **Available dynamic variants:** `stock_management`, `subscriptions`, `shipping`, `tax`, `coupon`, `license`, `digital_downloads`, and any other registered module key.
152
+ * **Source:** `app/Http/Controllers/ModuleSettingsController.php` (line 58)
153
+
154
+ #### Parameters:
155
+ * `$moduleData` *(array)* — The newly saved settings for this module (`['active' => 'no', ...]`)
156
+ * `$prevModuleData` *(array)* — The previous settings for this module before the save (`['active' => 'yes', ...]`)
157
+
158
+ #### Usage Example:
159
+ ```php
160
+ // Hook when stock management module is deactivated
161
+ add_action('fluent_cart/module/deactivated/stock_management', function ($moduleData, $prevModuleData) {
162
+ // Clean up stock-related cron jobs when stock management is turned off
163
+ as_unschedule_all_actions('fluent_cart/stock_check');
164
+ }, 10, 2);
165
+ ```
166
+
167
+ ---
168
+
169
+ ### `module/activated/{module_key}`
170
+ `fluent_cart/module/activated/{$moduleKey}` — Module activated (dynamic)
171
+
172
+ * **When it runs:** Fires inside `ModuleSettingsController::saveSettings()` when a module's active status transitions from `'no'` to `'yes'`. The `{$moduleKey}` portion is replaced dynamically with the module identifier.
173
+ * **Available dynamic variants:** `stock_management`, `subscriptions`, `shipping`, `tax`, `coupon`, `license`, `digital_downloads`, and any other registered module key.
174
+ * **Source:** `app/Http/Controllers/ModuleSettingsController.php` (line 61)
175
+
176
+ #### Parameters:
177
+ * `$moduleData` *(array)* — The newly saved settings for this module (`['active' => 'yes', ...]`)
178
+ * `$prevModuleData` *(array)* — The previous settings for this module before the save (`['active' => 'no', ...]`)
179
+
180
+ #### Usage Example:
181
+ ```php
182
+ // Hook when subscriptions module is activated
183
+ add_action('fluent_cart/module/activated/subscriptions', function ($moduleData, $prevModuleData) {
184
+ // Run database migrations when subscriptions module is first activated
185
+ \FluentCart\Database\DBMigrator::run('subscription_tables');
186
+ }, 10, 2);
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Block Editor / Email Editor
192
+ Hooks for the custom FluentCart block editor used to compose email templates. These fire during the editor page lifecycle and asset loading.
193
+
194
+ ### `fluent_cart_enqueue_block_editor_assets`
195
+ `fluent_cart_enqueue_block_editor_assets` — Block editor assets being enqueued
196
+
197
+ * **When it runs:** Fires at the end of `FluentCartBlockEditorHandler::enqueueEditorStyles()`, after all core WordPress block editor styles (`wp-edit-post`, `wp-block-library`, etc.) have been enqueued. WordPress's own `wp_enqueue_editor_format_library_assets` is also attached to this hook. Use it to add custom styles or scripts to the email block editor.
198
+ * **Parameters:** None.
199
+ * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 428)
200
+
201
+ #### Usage Example:
202
+ ```php
203
+ // Hook when email block editor assets are enqueued
204
+ add_action('fluent_cart_enqueue_block_editor_assets', function () {
205
+ // Add custom styles for the email block editor page
206
+ wp_enqueue_style('my-email-editor-styles', plugins_url('css/email-editor.css', __FILE__));
207
+ }, 10);
208
+ ```
209
+
210
+ ---
211
+
212
+ ### `fluent_cart_block_editor/head`
213
+ `fluent_cart_block_editor/head` — In `<head>` of custom block editor page
214
+
215
+ * **When it runs:** Fires inside the `<head>` tag of the custom block editor HTML page. WordPress core hooks (`wp_enqueue_scripts`, `wp_print_styles`, `wp_print_head_scripts`, etc.) are pre-attached to this action so that editor stylesheets and scripts are output in the correct location. Use this to inject additional `<meta>`, `<link>`, or `<style>` tags into the editor page head.
216
+ * **Parameters:** None.
217
+ * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 620)
218
+
219
+ #### Usage Example:
220
+ ```php
221
+ // Hook inside head tag of custom block editor page
222
+ add_action('fluent_cart_block_editor/head', function () {
223
+ // Inject a custom Google font stylesheet link into the editor head
224
+ echo '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap">';
225
+ }, 20);
226
+ ```
227
+
228
+ ---
229
+
230
+ ### `block_editor_head`
231
+ `fluent_cart/block_editor_head` — Second head hook in block editor page
232
+
233
+ * **When it runs:** Fires immediately after `fluent_cart_block_editor/head` inside the `<head>` tag, right before the closing `</head>`. This is a secondary head hook — use it for last-minute style overrides or scripts that must load after everything else in the head.
234
+ * **Parameters:** None.
235
+ * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 622)
236
+
237
+ #### Usage Example:
238
+ ```php
239
+ // Secondary head hook right before closing head tag in block editor
240
+ add_action('fluent_cart/block_editor_head', function () {
241
+ // Override editor font family styles as final head injection
242
+ echo '<style>.editor-styles-wrapper { font-family: "Inter", sans-serif; }</style>';
243
+ }, 10);
244
+ ```
245
+
246
+ ---
247
+
248
+ ### `new_block_editor_footer`
249
+ `fluent_cart/new_block_editor_footer` — Footer of custom block editor page (for JS)
250
+
251
+ * **When it runs:** Fires inside the `<body>` of the custom block editor page, after the editor `<div>` and before `</body>`. This is the recommended place to inject footer JavaScript for the email editor.
252
+ * **Parameters:** None.
253
+ * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 629)
254
+
255
+ #### Usage Example:
256
+ ```php
257
+ // Hook inside body of custom block editor page before closing body tag
258
+ add_action('fluent_cart/new_block_editor_footer', function () {
259
+ // Inject custom JavaScript into email editor page footer
260
+ echo '<script>console.log("FluentCart email editor loaded");</script>';
261
+ }, 10);
262
+ ```
263
+
264
+ ---
265
+
266
+ ### `block_editor/enqueue_assets`
267
+ `fluent_cart/block_editor/enqueue_assets` — After email editor block assets enqueued
268
+
269
+ * **When it runs:** Fires at the end of `FluentCartBlockEditorHandler::enqueueEmailEditorBlocks()`, after all FluentCart-specific email editor block scripts, styles, and global editor SCSS have been enqueued. Use this to register additional custom blocks or scripts for the email editor.
270
+ * **Parameters:** None.
271
+ * **Source:** `app/Hooks/Handlers/FluentCartBlockEditorHandler.php` (line 1232)
272
+
273
+ #### Usage Example:
274
+ ```php
275
+ // Hook after email editor block scripts and styles are enqueued
276
+ add_action('fluent_cart/block_editor/enqueue_assets', function () {
277
+ // Register custom email block script for editor
278
+ wp_enqueue_script('my-email-block', plugins_url('js/my-email-block.js', __FILE__), ['wp-blocks'], '1.0', true);
279
+ }, 10);
280
+ ```
281
+
282
+ ---
283
+
284
+ ### `block_editor/render_block`
285
+ `fluent_cart/block_editor/render_block` — Render unknown block types in email parser
286
+
287
+ * **When it runs:** Fires inside `FluentBlockParser` when processing a block whose name is not recognised by any built-in handler and is not a standard email editor block. The hook runs inside `ob_start()` — any output you echo will be captured and used as the block's rendered HTML in the email. If nothing is output, the parser falls back to raw innerHTML.
288
+ * **Source:** `app/Services/Email/FluentBlockParser.php` (line 278)
289
+
290
+ #### Parameters:
291
+ `$data` *(array)*: Block rendering context
292
+ ```php
293
+ $data = [
294
+ 'block' => [...], // array — Full block array (name, attrs, innerBlocks, innerHTML, etc.)
295
+ 'block_name' => 'my/custom', // string — The block type name string
296
+ 'attributes' => [...], // array — Block attributes array
297
+ ];
298
+ ```
299
+
300
+ #### Usage Example:
301
+ ```php
302
+ // Hook to render unrecognized block types in email parser
303
+ add_action('fluent_cart/block_editor/render_block', function ($data) {
304
+ // Check block type name match
305
+ if ($data['block_name'] === 'my-plugin/promo-banner') {
306
+ $heading = $data['attributes']['heading'] ?? 'Special Offer';
307
+ // Echo rendered HTML for custom promo banner block
308
+ echo '<div style="background: #f0f0f0; padding: 20px; text-align: center;">';
309
+ echo '<h2>' . esc_html($heading) . '</h2>';
310
+ echo '</div>';
311
+ }
312
+ }, 10, 1);
313
+ ```
314
+
315
+ ---
316
+
317
+ ## Form Rendering
318
+
319
+ ### `render_custom_form_field`
320
+ `fluent_cart/render_custom_form_field` — Unrecognised form field type fallback
321
+
322
+ * **When it runs:** Fires inside the `default` case of `FormFieldRenderer::renderField()` when the field type does not match any built-in type (`section`, `sub_section`, `text`, `email`, `tel`, `number`, `textarea`, `checkbox`, `select`, `address_select`). Use this to render custom field types in the checkout or registration forms.
323
+ * **Source:** `app/Services/Renderer/FormFieldRenderer.php` (line 58)
324
+
325
+ #### Parameters:
326
+ `$fieldData` *(array)*: The field configuration array
327
+ ```php
328
+ $fieldData = [
329
+ 'type' => 'my_custom_type', // string — The unrecognised field type
330
+ 'label' => 'Custom Field', // string — Field label
331
+ 'id' => 'my_field', // string — Field HTML ID
332
+ 'name' => 'my_field', // string — Field name attribute
333
+ 'required' => true, // bool — Whether the field is required
334
+ 'wrapper_class' => '', // string — CSS class for the wrapper
335
+ 'options' => [], // array — Options (if applicable)
336
+ ];
337
+ ```
338
+
339
+ #### Usage Example:
340
+ ```php
341
+ // Hook to render unrecognized form field types in checkout
342
+ add_action('fluent_cart/render_custom_form_field', function ($fieldData) {
343
+ // Render custom date_picker field type HTML
344
+ if ($fieldData['type'] === 'date_picker') {
345
+ $id = esc_attr($fieldData['id'] ?? '');
346
+ $name = esc_attr($fieldData['name'] ?? '');
347
+ $label = esc_html($fieldData['label'] ?? '');
348
+ $required = !empty($fieldData['required']) ? 'required' : '';
349
+ echo "<div class='fct_form_field'>";
350
+ echo "<label for='{$id}'>{$label}</label>";
351
+ echo "<input type='date' id='{$id}' name='{$name}' {$required} />";
352
+ echo "</div>";
353
+ }
354
+ }, 10, 1);
355
+ ```
356
+
357
+ ---
358
+
359
+ ## Templating
360
+ Hooks for the generic fallback template used on product archive pages and other FluentCart template-driven pages. They fire in sequence from top to bottom of the page layout.
361
+
362
+ ### `generic_template/rendering`
363
+ `fluent_cart/generic_template/rendering` — Start of generic fallback template
364
+
365
+ * **When it runs:** Fires at the very top of `fallback-generic-template.php`, before `get_header()` is called. Use this to set up global variables, enqueue assets, or modify the page state before any template output begins.
366
+ * **Parameters:** None.
367
+ * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 7)
368
+
369
+ #### Usage Example:
370
+ ```php
371
+ // Hook at top of generic fallback template before get_header()
372
+ add_action('fluent_cart/generic_template/rendering', function () {
373
+ // Enqueue custom styles for product archive template
374
+ wp_enqueue_style('my-archive-styles', plugins_url('css/archive.css', __FILE__));
375
+ }, 10);
376
+ ```
377
+
378
+ ---
379
+
380
+ ### `generic_template/before_content`
381
+ `fluent_cart/generic_template/before_content` — After get_header(), before main wrapper
382
+
383
+ * **When it runs:** Fires after the WordPress header has been rendered by `get_header()` and before the main content wrapper `<div>` opens. Use this for banners, breadcrumbs, or other full-width elements above the content area.
384
+ * **Parameters:** None.
385
+ * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 10)
386
+
387
+ #### Usage Example:
388
+ ```php
389
+ // Hook after get_header() and before main wrapper in generic template
390
+ add_action('fluent_cart/generic_template/before_content', function () {
391
+ // Add breadcrumb trail above product archive
392
+ echo '<nav class="fct-breadcrumb">Home &raquo; Shop</nav>';
393
+ }, 10);
394
+ ```
395
+
396
+ ---
397
+
398
+ ### `template/before_content`
399
+ `fluent_cart/template/before_content` — Inside main wrapper, before content
400
+
401
+ * **When it runs:** Fires inside the `<div id="main">` site-main wrapper, before the main content hook. Use this for content-width elements like filter bars or category headers that sit above the product grid.
402
+ * **Parameters:** None.
403
+ * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 13)
404
+
405
+ #### Usage Example:
406
+ ```php
407
+ // Hook inside main wrapper before main content area
408
+ add_action('fluent_cart/template/before_content', function () {
409
+ // Show category filter bar above product grid
410
+ echo '<div class="fct-filter-bar">Filter by category...</div>';
411
+ }, 10);
412
+ ```
413
+
414
+ ---
415
+
416
+ ### `template/main_content`
417
+ `fluent_cart/template/main_content` — Main content area
418
+
419
+ * **When it runs:** Fires inside the `<div id="main">` wrapper between the `before_content` and `after_content` hooks. This is where the primary page content (product grid, archive loop, etc.) is rendered. FluentCart's templating module hooks its archive rendering here.
420
+ * **Parameters:** None.
421
+ * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 14)
422
+
423
+ #### Usage Example:
424
+ ```php
425
+ // Hook inside main wrapper to render primary page content
426
+ add_action('fluent_cart/template/main_content', function () {
427
+ // Output custom product grid layout HTML
428
+ echo '<div class="my-custom-product-grid">Custom grid here</div>';
429
+ }, 10);
430
+ ```
431
+
432
+ ---
433
+
434
+ ### `template/after_content`
435
+ `fluent_cart/template/after_content` — After main content
436
+
437
+ * **When it runs:** Fires inside the `<div id="main">` wrapper after the main content has been rendered. Use this for pagination, call-to-action blocks, or related products sections that sit below the product grid.
438
+ * **Parameters:** None.
439
+ * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 15)
440
+
441
+ #### Usage Example:
442
+ ```php
443
+ // Hook inside main wrapper after primary page content
444
+ add_action('fluent_cart/template/after_content', function () {
445
+ // Render pagination elements below product grid
446
+ echo '<div class="fct-pagination"><!-- pagination links --></div>';
447
+ }, 10);
448
+ ```
449
+
450
+ ---
451
+
452
+ ### `generic_template/after_content`
453
+ `fluent_cart/generic_template/after_content` — After main wrapper, before get_footer()
454
+
455
+ * **When it runs:** Fires after the main content wrapper `<div>` closes and before `get_footer()` renders the site footer. Use this for full-width elements below the content area like newsletter signups or related content.
456
+ * **Parameters:** None.
457
+ * **Source:** `app/Modules/Templating/fallback-generic-template.php` (line 18)
458
+
459
+ #### Usage Example:
460
+ ```php
461
+ // Hook after main wrapper closes and before get_footer()
462
+ add_action('fluent_cart/generic_template/after_content', function () {
463
+ // Output full-width newsletter signup section
464
+ echo '<section class="fct-newsletter">Subscribe to our newsletter</section>';
465
+ }, 10);
466
+ ```
467
+
468
+ ---
469
+
470
+ ## Views (Shortcode-Driven Rendering)
471
+ Hooks that render specific view partials on the checkout page, receipt emails, and customer-facing forms. These fire inside `ob_start()` / `ob_get_clean()` blocks — your callbacks should `echo` HTML output.
472
+
473
+ ### `views/checkout_page_cart_item_list`
474
+ `fluent_cart/views/checkout_page_cart_item_list` — Render cart item list on checkout
475
+
476
+ * **When it runs:** Fires inside `CheckoutController::getCheckoutSummary()` to render the cart item list partial on the checkout page. The output is captured via `ob_start()` and returned as part of the checkout summary AJAX response.
477
+ * **Source:** `app/Http/Controllers/CheckoutController.php` (line 39)
478
+
479
+ #### Parameters:
480
+ `$data` *(array)*: Checkout context
481
+ ```php
482
+ $data = [
483
+ 'checkout' => $checkOutHelper, // \FluentCart\App\Helpers\CartCheckoutHelper instance
484
+ 'items' => [...], // array — Cart items from $checkOutHelper->getItems()
485
+ ];
486
+ ```
487
+
488
+ #### Usage Example:
489
+ ```php
490
+ // Hook to render cart item list partial on checkout page
491
+ add_action('fluent_cart/views/checkout_page_cart_item_list', function ($data) {
492
+ // Extract items array from checkout data
493
+ $items = $data['items'];
494
+ echo '<div class="fct-cart-items">';
495
+ foreach ($items as $item) {
496
+ echo '<div class="fct-cart-item">' . esc_html($item['title'] ?? '') . '</div>';
497
+ }
498
+ echo '</div>';
499
+ }, 10, 1);
500
+ ```
501
+
502
+ ---
503
+
504
+ ### `views/checkout_page_registration_form`
505
+ `fluent_cart/views/checkout_page_registration_form` — Render registration form on checkout
506
+
507
+ * **When it runs:** Fires inside `CustomerRegistrationHandler::render()` to output the guest registration form on the checkout page. The output is captured via `ob_start()` and returned as the rendered form HTML.
508
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerRegistrationHandler.php` (line 79)
509
+
510
+ #### Parameters:
511
+ `$viewData` *(array)*: View context
512
+ ```php
513
+ $viewData = [
514
+ 'checkout' => $checkOutHelper, // \FluentCart\App\Helpers\CartCheckoutHelper instance
515
+ ];
516
+ ```
517
+
518
+ #### Usage Example:
519
+ ```php
520
+ // Hook to render guest registration form on checkout page
521
+ add_action('fluent_cart/views/checkout_page_registration_form', function ($viewData) {
522
+ // Extract checkout helper instance
523
+ $checkout = $viewData['checkout'];
524
+ echo '<div class="fct-registration-form">';
525
+ echo '<h3>Create an Account</h3>';
526
+ // Render custom registration input fields
527
+ echo '<input type="text" name="full_name" placeholder="Full Name" />';
528
+ echo '<input type="email" name="email" placeholder="Email" />';
529
+ echo '<input type="password" name="password" placeholder="Password" />';
530
+ echo '</div>';
531
+ }, 10, 1);
532
+ ```
533
+
534
+ ---
535
+
536
+ ### `views/checkout_page_login_form`
537
+ `fluent_cart/views/checkout_page_login_form` — Render login form on checkout
538
+
539
+ * **When it runs:** Fires inside `CustomerLoginHandler::render()` to output the login form on the checkout page for returning customers. The output is captured via `ob_start()` and returned as the rendered form HTML.
540
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerLoginHandler.php` (line 81)
541
+
542
+ #### Parameters:
543
+ `$viewData` *(array)*: View context (same structure as `registration_form`)
544
+
545
+ #### Usage Example:
546
+ ```php
547
+ // Hook to render returning customer login form on checkout page
548
+ add_action('fluent_cart/views/checkout_page_login_form', function ($viewData) {
549
+ // Render login form inputs and submit button
550
+ echo '<div class="fct-login-form">';
551
+ echo '<h3>Returning Customer? Log In</h3>';
552
+ echo '<input type="email" name="email" placeholder="Email" />';
553
+ echo '<input type="password" name="password" placeholder="Password" />';
554
+ echo '<button type="submit">Log In</button>';
555
+ echo '</div>';
556
+ }, 10, 1);
557
+ ```
558
+
559
+ ---
560
+
561
+ ### `views/checkout_order_summary`
562
+ `fluent_cart/views/checkout_order_summary` — Render order summary (email shortcodes)
563
+
564
+ * **When it runs:** Fires inside `ShortcodeParser::getSummary()` when the shortcode is parsed in email templates. The output is captured via `ob_start()` and inserted into the email body as the order summary block. Receives the Order model instance.
565
+ * **Source:** `app/Services/ShortCodeParser/ShortcodeParser.php` (line 248)
566
+
567
+ #### Parameters:
568
+ `$data` *(array)*: Order summary context
569
+ ```php
570
+ $data = [
571
+ 'order' => $order, // \FluentCart\App\Models\Order instance
572
+ 'paymentReceipt' => $paymentReceipt, // \FluentCart\App\Services\PaymentReceipt instance
573
+ ];
574
+ ```
575
+
576
+ #### Usage Example:
577
+ ```php
578
+ // Hook to render order summary block in email shortcodes
579
+ add_action('fluent_cart/views/checkout_order_summary', function ($data) {
580
+ // Extract order model and payment receipt instances
581
+ $order = $data['order'];
582
+ $receipt = $data['paymentReceipt'];
583
+ echo '<table class="fct-order-summary">';
584
+ echo '<tr><th>Order #' . esc_html($order->id) . '</th></tr>';
585
+ // Render order summary table rows
586
+ echo '</table>';
587
+ }, 10, 1);
588
+ ```
589
+
590
+ ---
591
+
592
+ ### `views/checkout_order_receipt`
593
+ `fluent_cart/views/checkout_order_receipt` — Render full order receipt (email shortcodes)
594
+
595
+ * **When it runs:** Fires inside `ShortcodeParser::getReceipt()` when the shortcode is parsed in email templates. The output is captured via `ob_start()` and inserted into the email body as the complete Order receipt.
596
+ * **Source:** `app/Services/ShortCodeParser/ShortcodeParser.php` (line 256)
597
+
598
+ #### Parameters:
599
+ `$data` *(array)*: Order receipt context (same structure as `checkout_order_summary`)
600
+
601
+ #### Usage Example:
602
+ ```php
603
+ // Hook to render full order receipt block in email shortcodes
604
+ add_action('fluent_cart/views/checkout_order_receipt', function ($data) {
605
+ // Extract order model and payment receipt instances
606
+ $order = $data['order'];
607
+ $receipt = $data['paymentReceipt'];
608
+ echo '<div class="fct-receipt">';
609
+ echo '<h2>Receipt for Order #' . esc_html($order->id) . '</h2>';
610
+ // Render full receipt wrapper HTML
611
+ echo '</div>';
612
+ }, 10, 1);
613
+ ```
614
+
615
+ ---
616
+
617
+ ### `views/checkout_page_shipping_method_list`
618
+ `fluent_cart/views/checkout_page_shipping_method_list` — Render shipping method list
619
+
620
+ * **When it runs:** Fires inside `ShippingFrontendController::getShippingMethodsListView()` to render the list of available `ShippingMethod` instances on the checkout page. The output is captured via `ob_start()` and returned as part of the shipping methods AJAX response.
621
+ * **Source:** `app/Modules/Shipping/Http/Controllers/Frontend/ShippingFrontendController.php` (line 75)
622
+
623
+ #### Parameters:
624
+ `$data` *(array)*: Shipping methods context
625
+ ```php
626
+ $data = [
627
+ 'shipping_methods' => [
628
+ // Array of available \FluentCart\App\Models\ShippingMethod instances filtered by country
629
+ ],
630
+ ];
631
+ ```
632
+
633
+ #### Usage Example:
634
+ ```php
635
+ // Hook to render shipping method list partial on checkout page
636
+ add_action('fluent_cart/views/checkout_page_shipping_method_list', function ($data) {
637
+ // Extract filtered shipping methods list array
638
+ $methods = $data['shipping_methods'];
639
+ echo '<div class="fct-shipping-methods">';
640
+ foreach ($methods as $method) {
641
+ echo '<label>';
642
+ echo '<input type="radio" name="shipping_method" value="' . esc_attr($method->id) . '" />';
643
+ echo esc_html($method->title);
644
+ echo '</label>';
645
+ }
646
+ echo '</div>';
647
+ }, 10, 1);
648
+ ```
649
+
650
+ ---
651
+
652
+ ### `views/checkout_page_form_address_info_wrapper`
653
+ `fluent_cart/views/checkout_page_form_address_info_wrapper` — Render address info card
654
+
655
+ * **When it runs:** Fires inside `CustomerController` when rendering the address information card on the checkout page after a customer selects or submits their address. The output is captured via `ob_start()` and returned in the AJAX response.
656
+ * **Source:** `app/Http/Controllers/FrontendControllers/CustomerController.php` (line 137)
657
+
658
+ #### Parameters:
659
+ `$data` *(array)*: Address display data
660
+ ```php
661
+ $data = [
662
+ 'name' => 'John Doe', // string — Customer name
663
+ 'phone' => '+1234567890', // string — Customer phone number
664
+ 'label' => 'Home', // string — Address label
665
+ 'address' => '123 Main St, City, State, Country', // string — Formatted address string
666
+ ];
667
+ ```
668
+
669
+ #### Usage Example:
670
+ ```php
671
+ // Hook to render address info card view on checkout page
672
+ add_action('fluent_cart/views/checkout_page_form_address_info_wrapper', function ($data) {
673
+ // Render formatted address info card block
674
+ echo '<div class="fct-address-card">';
675
+ echo '<strong>' . esc_html($data['name']) . '</strong>';
676
+ if (!empty($data['phone'])) {
677
+ echo '<br />' . esc_html($data['phone']);
678
+ }
679
+ echo '<br />' . esc_html($data['address']);
680
+ echo '</div>';
681
+ }, 10, 1);
682
+ ```
683
+
684
+ ---
685
+
686
+ ## Policies / Security
687
+ Hooks that fire during REST API policy verification. These allow you to add custom security checks, rate limiting, or audit logging before the standard permission check runs.
688
+
689
+ ### `policy/store_sensitive_request`
690
+ `fluent_cart/policy/store_sensitive_request` — Store-sensitive API request verification
691
+
692
+ * **When it runs:** Fires at the beginning of `StoreSensitivePolicy::verifyRequest()`, before the `store/sensitive` capability check is performed. This policy protects sensitive store operations (e.g. payment gateway configuration, API key management). Use this to add additional security measures like IP whitelisting or two-factor verification.
693
+ * **Source:** `app/Http/Policies/StoreSensitivePolicy.php` (line 11)
694
+
695
+ #### Parameters:
696
+ `$data` *(array)*: Request context
697
+ ```php
698
+ $data = [
699
+ 'request' => $request, // \FluentCart\Framework\Http\Request\Request instance
700
+ ];
701
+ ```
702
+
703
+ #### Usage Example:
704
+ ```php
705
+ // Hook before store-sensitive REST API capability check is performed
706
+ add_action('fluent_cart/policy/store_sensitive_request', function ($data) {
707
+ // Extract request object and remote IP address
708
+ $request = $data['request'];
709
+ $ip = $request->server('REMOTE_ADDR');
710
+
711
+ // Log sensitive API access attempt details
712
+ fluent_cart_add_log(
713
+ 'Sensitive API Access',
714
+ sprintf('IP: %s, Endpoint: %s', $ip, $request->url()),
715
+ 'info'
716
+ );
717
+ }, 10, 1);
718
+ ```
719
+
720
+ ---
721
+
722
+ ### `policy/store_settings_request`
723
+ `fluent_cart/policy/store_settings_request` — Store-settings API request verification
724
+
725
+ * **When it runs:** Fires at the beginning of `StoreSettingsPolicy::verifyRequest()`, before the route-meta permission check (`hasRoutePermissions()`) is performed. This policy protects store settings endpoints (e.g. general settings, email templates, checkout configuration). Use this for additional validation or logging.
726
+ * **Source:** `app/Http/Policies/StoreSettingsPolicy.php` (line 11)
727
+
728
+ #### Parameters:
729
+ `$data` *(array)*: Request context (same structure as `store_sensitive_request`)
730
+
731
+ #### Usage Example:
732
+ ```php
733
+ // Hook before store-settings REST API capability check is performed
734
+ add_action('fluent_cart/policy/store_settings_request', function ($data) {
735
+ // Extract request object
736
+ $request = $data['request'];
737
+
738
+ // Restrict settings changes to specific allowed admin user IDs
739
+ $allowedUserIds = [1, 2, 3];
740
+ if (!in_array(get_current_user_id(), $allowedUserIds)) {
741
+ wp_die('You are not allowed to modify store settings.', 403);
742
+ }
743
+ }, 10, 1);
744
+ ```
745
+
746
+ ---
747
+
748
+ ## Web Routes
749
+ Dynamic hooks for custom web route endpoints. Used primarily by payment gateways for IPN (Instant Payment Notification) callbacks, webhook handlers, and other server-to-server endpoints.
750
+
751
+ ### `fluent_cart_action_{page}`
752
+ `fluent_cart_action_{$page}` — Custom web route action handler (dynamic)
753
+
754
+ * **When it runs:** Fires inside `WebRoutes` when the current FluentCart web route `$page` slug matches a registered action. After the action fires, `die()` is called immediately — your callback must handle the full response (headers, body, exit). This is typically used by payment gateway modules to register IPN/webhook listeners (e.g. `fluent_cart_action_stripe_ipn`).
755
+ * **Source:** `app/Http/Routes/WebRoutes.php` (line 198)
756
+
757
+ #### Parameters:
758
+ `$requestData` *(array)*: All request parameters from `App::request()->all()`, which includes merged GET and POST data.
759
+ ```php
760
+ $requestData = [
761
+ 'webhook_id' => 'evt_123abc',
762
+ 'payment_type' => 'subscription',
763
+ // ... any other query string and POST body parameters
764
+ ];
765
+ ```
766
+
767
+ #### Usage Example:
768
+ ```php
769
+ // Hook for custom web route IPN callback action handler
770
+ add_action('fluent_cart_action_my_gateway_ipn', function ($requestData) {
771
+ // Verify incoming HTTP webhook payload and signature
772
+ $payload = file_get_contents('php://input');
773
+ $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
774
+
775
+ if (!verify_webhook_signature($payload, $signature)) {
776
+ status_header(403);
777
+ echo 'Invalid signature';
778
+ return;
779
+ }
780
+
781
+ // Process IPN payment notification payload
782
+ process_ipn_notification($requestData);
783
+
784
+ status_header(200);
785
+ echo 'OK';
786
+ }, 10, 1);
787
+ ```