fluentcart-developer 2.3.0 → 2.3.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 (49) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +2301 -2161
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
@@ -1,1598 +1,1598 @@
1
- # Filter Hooks: Integrations & Advanced
2
-
3
- All filters related to external integrations, file storage, templates, License management, and advanced features.
4
-
5
- ---
6
-
7
- ## Integration Actions & Feeds
8
-
9
- ### `order_integrations`
10
- `fluent_cart/integration/order_integrations` — Filter all registered order integrations
11
-
12
- * **When it runs:** Applied when retrieving the list of all registered order integrations across event listeners, controllers, settings, and addons.
13
- * **Source:** `IntegrationEventListener.php` (lines 54, 247, 386), `IntegrationController.php` (lines 96, 150), `ProductIntegrationsController.php` (lines 18, 48), `GlobalIntegrationSettings.php` (line 84)
14
-
15
- #### Parameters:
16
- * `$integrations` *(array)* — Array of registered integrations (`MailChimp`, `FluentCRM`, etc.)
17
- * **Returns:** *(array)* — The modified integrations array
18
-
19
- #### Usage Example:
20
- ```php
21
- // Filter array of registered order integrations in FluentCart
22
- add_filter('fluent_cart/integration/order_integrations', function ($integrations) {
23
- // Add custom CRM integration definition array
24
- $integrations['custom_crm'] = [
25
- 'title' => 'Custom CRM',
26
- 'logo' => 'https://example.com/crm-logo.png',
27
- 'enabled' => true,
28
- ];
29
- return $integrations;
30
- });
31
- ```
32
-
33
- ---
34
-
35
- ### `run_all_actions_on_async`
36
- `fluent_cart/integration/run_all_actions_on_async` — Force all integration actions to run asynchronously
37
-
38
- * **When it runs:** Controls whether integration actions should be dispatched asynchronously instead of immediately during order processing.
39
- * **Source:** `IntegrationEventListener.php` (line 145)
40
-
41
- #### Parameters:
42
- * `$async` *(bool)* — Whether to force async execution (default: `false`)
43
- * `$order` *(\FluentCart\App\Models\Order)* — The order model instance
44
- * `$hook` *(string)* — The integration hook being fired
45
- * **Returns:** *(bool)* — Whether to run actions asynchronously
46
-
47
- #### Usage Example:
48
- ```php
49
- // Force integration actions to dispatch asynchronously for large orders
50
- add_filter('fluent_cart/integration/run_all_actions_on_async', function ($async, $order, $hook) {
51
- // Force async execution for orders exceeding $1,000 total
52
- if ($order->total > 100000) {
53
- return true;
54
- }
55
- return $async;
56
- }, 10, 3);
57
- ```
58
-
59
- ---
60
-
61
- ### `global_notification_types`
62
- `fluent_cart/integration/global_notification_types` — Filter available notification types
63
-
64
- * **When it runs:** Applied when retrieving the list of available global notification types for integrations.
65
- * **Source:** `GlobalIntegrationSettings.php` (line 119)
66
-
67
- #### Parameters:
68
- * `$types` *(array)* — Array of notification types (`email`, etc.)
69
- * **Returns:** *(array)* — The modified notification types array
70
-
71
- #### Usage Example:
72
- ```php
73
- // Filter available global integration notification types array
74
- add_filter('fluent_cart/integration/global_notification_types', function ($types) {
75
- // Append SMS notification type definition
76
- $types['sms'] = [
77
- 'title' => 'SMS Notification',
78
- 'description' => 'Send SMS notifications on order events',
79
- ];
80
- return $types;
81
- });
82
- ```
83
-
84
- ---
85
-
86
- ### `global_notification_feed_{$feed_key}`
87
- `fluent_cart/integration/global_notification_feed_{$feed_key}` — Filter notification feed data (DYNAMIC)
88
-
89
- * **When it runs:** Dynamic filter applied when retrieving notification feed data for a specific feed key.
90
- * **Source:** `GlobalIntegrationSettings.php` (line 151)
91
-
92
- #### Parameters:
93
- * `$feedData` *(array)* — The notification feed data array
94
- * **Returns:** *(array)* — The modified feed data array
95
-
96
- #### Usage Example:
97
- ```php
98
- // Filter notification feed data array for email alerts feed
99
- add_filter('fluent_cart/integration/global_notification_feed_email_alerts', function ($feedData) {
100
- // Append additional admin email recipient to feed data
101
- $feedData['recipients'][] = 'extra-admin@example.com';
102
- return $feedData;
103
- });
104
- ```
105
-
106
- ---
107
-
108
- ### `get_global_integration_actions`
109
- `fluent_cart/integration/get_global_integration_actions` — Filter global integration actions
110
-
111
- * **When it runs:** Applied when retrieving available global integration actions triggered by order events.
112
- * **Source:** `GlobalIntegrationActionHandler.php` (line 22)
113
-
114
- #### Parameters:
115
- * `$actions` *(array)* — Array of integration actions (default: `[]`)
116
- * **Returns:** *(array)* — The modified integration actions array
117
-
118
- #### Usage Example:
119
- ```php
120
- // Filter available global integration actions list
121
- add_filter('fluent_cart/integration/get_global_integration_actions', function ($actions) {
122
- // Append custom webhook action definition to integration actions
123
- $actions['custom_webhook'] = [
124
- 'title' => 'Fire Custom Webhook',
125
- 'enabled' => true,
126
- ];
127
- return $actions;
128
- });
129
- ```
130
-
131
- ---
132
-
133
- ### `notifying_async_{$feedKey}`
134
- `fluent_cart/integration/notifying_async_{$feedKey}` — Control async notification per feed (DYNAMIC)
135
-
136
- * **When it runs:** Dynamic filter controlling whether a specific notification feed is processed asynchronously (default: `true`).
137
- * **Source:** `GlobalNotificationHandler.php` (line 104)
138
-
139
- #### Parameters:
140
- * `$async` *(bool)* — Whether to process notification asynchronously (default: `true`)
141
- * **Returns:** *(bool)* — Whether to use async processing
142
-
143
- #### Usage Example:
144
- ```php
145
- // Control async notification dispatch for email alerts feed
146
- add_filter('fluent_cart/integration/notifying_async_email_alerts', function ($async) {
147
- // Force synchronous processing for email alerts notification feed
148
- return false;
149
- });
150
- ```
151
-
152
- ---
153
-
154
- ### `webhook/payload` (Pro)
155
- `fluent_cart/webhook/payload` — Filter webhook payload before sending
156
-
157
- * **When it runs:** Applied to webhook payload body after construction, before encoding and dispatching to external endpoint. Requires Pro plugin.
158
- * **Source:** `fluent-cart-pro/.../WebhookConnect.php` (line 251)
159
-
160
- #### Parameters:
161
- * `$payloadBody` *(array)* — Payload body data array
162
- * `$context` *(array)* — Context data (`['order' => Order, 'feed' => array, 'event_data' => array]`)
163
- * **Returns:** *(array)* — The modified payload body array
164
-
165
- #### Usage Example:
166
- ```php
167
- // Filter webhook payload array before sending to external endpoint (Pro)
168
- add_filter('fluent_cart/webhook/payload', function ($payloadBody, $context) {
169
- // Append custom tracking metadata to payload body
170
- $payloadBody['custom_meta'] = [
171
- 'source' => 'fluentcart',
172
- 'timestamp' => gmdate('Y-m-d H:i:s')
173
- ];
174
-
175
- // Remove customer email address from webhook payload
176
- unset($payloadBody['customer']['email']);
177
-
178
- return $payloadBody;
179
- }, 10, 2);
180
- ```
181
-
182
- ---
183
-
184
- ## Integration Settings & Configuration
185
-
186
- ### `global_integration_settings_{$key}`
187
- `fluent_cart/integration/global_integration_settings_{$key}` — Filter integration settings (DYNAMIC)
188
-
189
- * **When it runs:** Dynamic filter applied when retrieving settings for a specific integration (e.g. `mailchimp`, `zapier`).
190
- * **Source:** `GlobalIntegrationSettings.php` (line 24)
191
-
192
- #### Parameters:
193
- * `$settings` *(array)* — Integration settings array (default: `[]`)
194
- * **Returns:** *(array)* — The modified settings array
195
-
196
- #### Usage Example:
197
- ```php
198
- // Filter integration settings array for MailChimp integration
199
- add_filter('fluent_cart/integration/global_integration_settings_mailchimp', function ($settings) {
200
- // Override MailChimp API key from environment constant if defined
201
- $settings['api_key'] = defined('MAILCHIMP_API_KEY') ? MAILCHIMP_API_KEY : $settings['api_key'];
202
- return $settings;
203
- });
204
- ```
205
-
206
- ---
207
-
208
- ### `global_integration_fields_{$key}`
209
- `fluent_cart/integration/global_integration_fields_{$key}` — Filter integration field definitions (DYNAMIC)
210
-
211
- * **When it runs:** Dynamic filter applied when retrieving field definitions for an integration configuration form.
212
- * **Source:** `GlobalIntegrationSettings.php` (line 25)
213
-
214
- #### Parameters:
215
- * `$fields` *(array)* — Field definitions array (default: `[]`)
216
- * **Returns:** *(array)* — The modified field definitions array
217
-
218
- #### Usage Example:
219
- ```php
220
- // Filter integration configuration form fields for MailChimp
221
- add_filter('fluent_cart/integration/global_integration_fields_mailchimp', function ($fields) {
222
- // Append double opt-in checkbox field definition
223
- $fields[] = [
224
- 'key' => 'double_optin',
225
- 'label' => 'Enable Double Opt-in',
226
- 'type' => 'checkbox',
227
- ];
228
- return $fields;
229
- });
230
- ```
231
-
232
- ---
233
-
234
- ### `get_integration_defaults_{$name}`
235
- `fluent_cart/integration/get_integration_defaults_{$name}` — Filter integration defaults (DYNAMIC)
236
-
237
- * **When it runs:** Dynamic filter applied when retrieving default settings for a specific integration.
238
- * **Source:** `GlobalIntegrationSettings.php` (lines 199, 201)
239
-
240
- #### Parameters:
241
- * `$defaults` *(array)* — Default settings values array
242
- * **Returns:** *(array)* — The modified defaults array
243
-
244
- #### Usage Example:
245
- ```php
246
- // Filter default settings values for MailChimp integration
247
- add_filter('fluent_cart/integration/get_integration_defaults_mailchimp', function ($defaults) {
248
- // Set default audience list ID and tag array
249
- $defaults['list_id'] = 'default_list_123';
250
- $defaults['tags'] = ['fluentcart-customer'];
251
- return $defaults;
252
- });
253
- ```
254
-
255
- ---
256
-
257
- ### `get_integration_settings_fields_{$name}`
258
- `fluent_cart/integration/get_integration_settings_fields_{$name}` — Filter integration settings fields (DYNAMIC)
259
-
260
- * **When it runs:** Dynamic filter applied when retrieving settings field definitions for a specific integration.
261
- * **Source:** `GlobalIntegrationSettings.php` (lines 204, 276), `IntegrationHelper.php` (line 27)
262
-
263
- #### Parameters:
264
- * `$fields` *(array)* — Field definitions array (default: `[]`)
265
- * **Returns:** *(array)* — The modified field definitions array
266
-
267
- #### Usage Example:
268
- ```php
269
- // Filter settings form field definitions for Zapier integration
270
- add_filter('fluent_cart/integration/get_integration_settings_fields_zapier', function ($fields) {
271
- // Append webhook URL input field definition
272
- $fields[] = [
273
- 'key' => 'webhook_url',
274
- 'label' => 'Webhook URL',
275
- 'type' => 'url',
276
- 'required' => true,
277
- 'placeholder' => 'https://hooks.zapier.com/...',
278
- ];
279
- return $fields;
280
- });
281
- ```
282
-
283
- ---
284
-
285
- ### `save_integration_values_{$name}`
286
- `fluent_cart/integration/save_integration_values_{$name}` — Filter before saving integration data (DYNAMIC)
287
-
288
- * **When it runs:** Dynamic filter applied just before integration settings are saved to database.
289
- * **Source:** `GlobalIntegrationSettings.php` (line 248)
290
-
291
- #### Parameters:
292
- * `$integration` *(\FluentCart\App\Models\Meta)* — Meta model instance containing integration data
293
- * **Returns:** *(\FluentCart\App\Models\Meta)* — The modified Meta model instance
294
-
295
- #### Usage Example:
296
- ```php
297
- // Filter Meta model instance before saving MailChimp integration data
298
- add_filter('fluent_cart/integration/save_integration_values_mailchimp', function ($integration) {
299
- // Encrypt API key field value before persisting to database
300
- $value = $integration->value;
301
- if (!empty($value['api_key'])) {
302
- $value['api_key_encrypted'] = encrypt($value['api_key']);
303
- }
304
- $integration->value = $value;
305
- return $integration;
306
- });
307
- ```
308
-
309
- ---
310
-
311
- ### `get_integration_merge_fields_{$name}`
312
- `fluent_cart/integration/get_integration_merge_fields_{$name}` — Filter integration merge/mapping fields (DYNAMIC)
313
-
314
- * **When it runs:** Dynamic filter applied when retrieving merge fields for mapping FluentCart data to external service fields.
315
- * **Source:** `GlobalIntegrationSettings.php` (line 369)
316
-
317
- #### Parameters:
318
- * `$list` *(array)* — Merge fields list array
319
- * `$listId` *(string)* — Audience or list identifier
320
- * **Returns:** *(array)* — The modified merge fields array
321
-
322
- #### Usage Example:
323
- ```php
324
- // Filter integration merge mapping fields for MailChimp
325
- add_filter('fluent_cart/integration/get_integration_merge_fields_mailchimp', function ($list, $listId) {
326
- // Append Company Name field to merge fields mapping list
327
- $list[] = [
328
- 'key' => 'COMPANY',
329
- 'label' => 'Company Name',
330
- 'type' => 'text',
331
- ];
332
- return $list;
333
- }, 10, 2);
334
- ```
335
-
336
- ---
337
-
338
- ### `integration_options_{$key}`
339
- `fluent_cart/integration/integration_options_{$key}` — Filter dynamic integration options (DYNAMIC)
340
-
341
- * **When it runs:** Dynamic filter applied when retrieving option values for integration dropdown or selection fields.
342
- * **Source:** `IntegrationController.php` (line 302)
343
-
344
- #### Parameters:
345
- * `$options` *(array)* — Options array (default: `[]`)
346
- * **Returns:** *(array)* — The modified options array
347
-
348
- #### Usage Example:
349
- ```php
350
- // Filter dynamic dropdown option values for MailChimp lists
351
- add_filter('fluent_cart/integration/integration_options_mailchimp_lists', function ($options) {
352
- // Append custom audience option definition to list
353
- $options[] = [
354
- 'id' => 'custom_list',
355
- 'title' => 'Custom Audience',
356
- ];
357
- return $options;
358
- });
359
- ```
360
-
361
- ---
362
-
363
- ### `integration_saving_data_{$provider}`
364
- `fluent_cart/integration/integration_saving_data_{$provider}` — Filter integration data before validation (DYNAMIC)
365
-
366
- * **When it runs:** Dynamic filter applied to integration data before saving validation.
367
- * **Source:** `IntegrationHelper.php` (line 62)
368
-
369
- #### Parameters:
370
- * `$validatedData` *(array)* — Validated integration data array
371
- * **Returns:** *(array)* — The modified validated data array
372
-
373
- #### Usage Example:
374
- ```php
375
- // Filter MailChimp integration data before saving validation
376
- add_filter('fluent_cart/integration/integration_saving_data_mailchimp', function ($validatedData) {
377
- // Convert tag strings to lowercase before saving
378
- if (!empty($validatedData['tags'])) {
379
- $validatedData['tags'] = array_map('strtolower', $validatedData['tags']);
380
- }
381
- return $validatedData;
382
- });
383
- ```
384
-
385
- ---
386
-
387
- ### `editing_integration_{$key}`
388
- `fluent_cart/integration/editing_integration_{$key}` — Filter integration data when editing (DYNAMIC)
389
-
390
- * **When it runs:** Dynamic filter applied when an integration is loaded for editing in admin UI.
391
- * **Source:** `IntegrationHelper.php` (line 80)
392
-
393
- #### Parameters:
394
- * `$data` *(array)* — Integration data for editing
395
- * `$args` *(array)* — Additional context arguments
396
- * **Returns:** *(array)* — The modified integration data
397
-
398
- #### Usage Example:
399
- ```php
400
- // Filter integration data when loading for edit in admin UI
401
- add_filter('fluent_cart/integration/editing_integration_mailchimp', function ($data, $args) {
402
- // Decrypt API key for editing interface display
403
- if (!empty($data['api_key_encrypted'])) {
404
- $data['api_key'] = decrypt($data['api_key_encrypted']);
405
- }
406
- return $data;
407
- }, 10, 2);
408
- ```
409
-
410
- ---
411
-
412
- ## Integration Addons
413
-
414
- ### `addons`
415
- `fluent_cart/integration/addons` — Filter the integration addons list
416
-
417
- * **When it runs:** Applied when retrieving list of available integration addons in admin interface.
418
- * **Source:** `AddonsController.php` (line 87)
419
-
420
- #### Parameters:
421
- * `$addons` *(array)* — Array of addon definitions
422
- * **Returns:** *(array)* — The modified addons array
423
-
424
- #### Usage Example:
425
- ```php
426
- // Filter available integration addons list in admin panel
427
- add_filter('fluent_cart/integration/addons', function ($addons) {
428
- // Register custom integration addon definition
429
- $addons['my_addon'] = [
430
- 'title' => 'My Custom Addon',
431
- 'description' => 'Adds custom integration functionality',
432
- 'logo' => 'https://example.com/addon-logo.png',
433
- 'enabled' => true,
434
- ];
435
- return $addons;
436
- });
437
- ```
438
-
439
- ---
440
-
441
- ### `installable_repo_plugins`
442
- `fluent_cart/installable_repo_plugins` — Filter installable plugin recommendations
443
-
444
- * **When it runs:** Applied when retrieving recommended plugins installable from within FluentCart admin.
445
- * **Source:** `AddonsController.php` (line 121), `GlobalIntegrationSettings.php` (line 396)
446
-
447
- #### Parameters:
448
- * `$plugins` *(array)* — Array of installable plugin definitions
449
- * **Returns:** *(array)* — The modified plugins array
450
-
451
- #### Usage Example:
452
- ```php
453
- // Filter recommended plugins array installable from WP admin
454
- add_filter('fluent_cart/installable_repo_plugins', function ($plugins) {
455
- // Append FluentCRM plugin definition to recommended plugins list
456
- $plugins[] = [
457
- 'title' => 'FluentCRM',
458
- 'slug' => 'fluent-crm',
459
- 'description' => 'Email marketing automation',
460
- 'url' => 'https://wordpress.org/plugins/fluent-crm/',
461
- ];
462
- return $plugins;
463
- });
464
- ```
465
-
466
- ---
467
-
468
- ## File Storage & Downloads
469
-
470
- ### `local_file_blocked_extensions`
471
- `fluent_cart/local_file_blocked_extensions` — Filter blocked file extensions for local storage
472
-
473
- * **When it runs:** Applied when validating local storage file uploads to modify blocked extension list.
474
- * **Source:** `LocalDriver.php` (line 129)
475
-
476
- #### Parameters:
477
- * `$blockedExts` *(array)* — Array of blocked file extensions
478
- * `$localFilePath` *(string)* — Local file path
479
- * `$uploadToFilePath` *(string)* — Target upload path
480
- * `$fileInfo` *(array)* — File information array
481
- * **Returns:** *(array)* — The modified blocked extensions array
482
-
483
- #### Usage Example:
484
- ```php
485
- // Filter blocked file extensions array for local storage driver uploads
486
- add_filter('fluent_cart/local_file_blocked_extensions', function ($blockedExts, $localFilePath, $uploadToFilePath, $fileInfo) {
487
- // Add SVG and WebP extensions to blocked upload list
488
- $blockedExts[] = 'svg';
489
- $blockedExts[] = 'webp';
490
- return $blockedExts;
491
- }, 10, 4);
492
- ```
493
-
494
- ---
495
-
496
- ### `download_expiration_minutes`
497
- `fluent_cart/download_expiration_minutes` — Filter S3 download link expiration time
498
-
499
- * **When it runs:** Controls how long pre-signed S3 download URLs remain valid.
500
- * **Source:** `S3Driver.php` (lines 237, 252)
501
-
502
- #### Parameters:
503
- * `$expirationMinutes` *(int)* — Expiration time in minutes
504
- * `$context` *(array)* — Context data (`['file_path' => string, 'bucket' => string, 'driver' => 's3']`)
505
- * **Returns:** *(int)* — The modified expiration time in minutes
506
-
507
- #### Usage Example:
508
- ```php
509
- // Filter S3 pre-signed download link expiration time in minutes
510
- add_filter('fluent_cart/download_expiration_minutes', function ($expirationMinutes, $context) {
511
- // Extend download link validity to 120 minutes for ZIP files
512
- if (str_ends_with($context['file_path'], '.zip')) {
513
- return 120;
514
- }
515
- return $expirationMinutes;
516
- }, 10, 2);
517
- ```
518
-
519
- ---
520
-
521
- ### `download_link_validity_in_minutes`
522
- `fluent_cart/download_link_validity_in_minutes` — Filter download link validity duration
523
-
524
- * **When it runs:** Controls how long customer-facing download links remain valid (default: `60` minutes).
525
- * **Source:** `Helper.php` (line 1430)
526
-
527
- #### Parameters:
528
- * `$minutes` *(int)* — Link validity in minutes (default: `60`)
529
- * `$context` *(array)* — Context data (`['product_download' => Model, 'order_id' => int, 'is_admin' => bool]`)
530
- * **Returns:** *(int)* — The modified validity in minutes
531
-
532
- #### Usage Example:
533
- ```php
534
- // Filter customer-facing downloadable link validity duration in minutes
535
- add_filter('fluent_cart/download_link_validity_in_minutes', function ($minutes, $context) {
536
- // Grant 24-hour download link validity window for admin users
537
- if ($context['is_admin']) {
538
- return 1440;
539
- }
540
- return $minutes;
541
- }, 10, 2);
542
- ```
543
-
544
- ---
545
-
546
- ### `product_download/can_be_downloaded`
547
- `fluent_cart/product_download/can_be_downloaded` — Filter whether a file can be downloaded
548
-
549
- * **When it runs:** Applied during download validation to determine download permission.
550
- * **Source:** `FileDownloader.php` (line 95)
551
-
552
- #### Parameters:
553
- * `$canDownload` *(bool|\WP_Error)* — Download permission boolean or rejection `WP_Error`
554
- * **Returns:** *(bool|\WP_Error)* — The modified download permission
555
-
556
- #### Usage Example:
557
- ```php
558
- // Filter whether customer is permitted to download digital file
559
- add_filter('fluent_cart/product_download/can_be_downloaded', function ($canDownload) {
560
- // Block file downloads during maintenance mode
561
- if (get_option('fluent_cart_maintenance_mode')) {
562
- return new \WP_Error('maintenance', 'Downloads are temporarily disabled during maintenance.');
563
- }
564
- return $canDownload;
565
- });
566
- ```
567
-
568
- ---
569
-
570
- ### `get_global_storage_settings_{$driver}`
571
- `fluent_cart/storage/get_global_storage_settings_{$driver}` — Filter storage driver settings (DYNAMIC)
572
-
573
- * **When it runs:** Dynamic filter applied when retrieving settings for a specific storage driver (`s3`, `local`).
574
- * **Source:** `api/StorageDrivers.php` (line 18)
575
-
576
- #### Parameters:
577
- * `$settings` *(array)* — Storage driver settings array (default: `[]`)
578
- * **Returns:** *(array)* — The modified settings array
579
-
580
- #### Usage Example:
581
- ```php
582
- // Filter global S3 storage driver settings array
583
- add_filter('fluent_cart/storage/get_global_storage_settings_s3', function ($settings) {
584
- // Override S3 bucket and region from environment constants if set
585
- $settings['bucket'] = defined('S3_BUCKET') ? S3_BUCKET : $settings['bucket'];
586
- $settings['region'] = defined('S3_REGION') ? S3_REGION : $settings['region'];
587
- return $settings;
588
- });
589
- ```
590
-
591
- ---
592
-
593
- ### `get_global_storage_drivers`
594
- `fluent_cart/storage/get_global_storage_drivers` — Filter all available storage drivers
595
-
596
- * **When it runs:** Applied when retrieving list of all available storage drivers.
597
- * **Source:** `StorageDrivers.php` (line 28)
598
-
599
- #### Parameters:
600
- * `$drivers` *(array)* — Array of storage driver definitions (default: `[]`)
601
- * **Returns:** *(array)* — The modified drivers array
602
-
603
- #### Usage Example:
604
- ```php
605
- // Filter available file storage driver definitions array
606
- add_filter('fluent_cart/storage/get_global_storage_drivers', function ($drivers) {
607
- // Register custom Backblaze B2 storage driver handler
608
- $drivers['backblaze'] = [
609
- 'title' => 'Backblaze B2',
610
- 'description' => 'Store files on Backblaze B2',
611
- 'handler' => 'BackblazeDriver',
612
- ];
613
- return $drivers;
614
- });
615
- ```
616
-
617
- ---
618
-
619
- ### `get_global_storage_driver_status_{$driver}`
620
- `fluent_cart/storage/get_global_storage_driver_status_{$driver}` — Filter storage driver status (DYNAMIC)
621
-
622
- * **When it runs:** Dynamic filter retrieving connection status for a specific storage driver.
623
- * **Source:** `StorageDrivers.php` (line 65)
624
-
625
- #### Parameters:
626
- * `$status` *(array)* — Driver status array (default: `[]`)
627
- * **Returns:** *(array)* — The modified status array
628
-
629
- #### Usage Example:
630
- ```php
631
- // Filter connection status array for S3 storage driver
632
- add_filter('fluent_cart/storage/get_global_storage_driver_status_s3', function ($status) {
633
- // Set connected status and success message for S3 driver
634
- $status['connected'] = true;
635
- $status['message'] = 'Connected to S3 bucket successfully';
636
- return $status;
637
- });
638
- ```
639
-
640
- ---
641
-
642
- ### `verify_driver_connect_info_{$driver}`
643
- `fluent_cart/verify_driver_connect_info_{$driver}` — Filter driver connection verification (DYNAMIC)
644
-
645
- * **When it runs:** Dynamic filter applied when verifying connection info for a storage driver.
646
- * **Source:** `StorageDrivers.php` (line 79)
647
-
648
- #### Parameters:
649
- * `$settings` *(array)* — Driver connection settings array
650
- * **Returns:** *(array)* — The modified settings array
651
-
652
- #### Usage Example:
653
- ```php
654
- // Filter S3 storage driver connection verification check
655
- add_filter('fluent_cart/verify_driver_connect_info_s3', function ($settings) {
656
- // Verify AWS S3 credentials via SDK bucket listing test
657
- try {
658
- $client = new \Aws\S3\S3Client($settings);
659
- $client->listBuckets();
660
- $settings['verified'] = true;
661
- } catch (\Exception $e) {
662
- $settings['error'] = $e->getMessage();
663
- }
664
- return $settings;
665
- });
666
- ```
667
-
668
- ---
669
-
670
- ### `storage_settings_before_update_{$slug}`
671
- `fluent_cart/storage/storage_settings_before_update_{$slug}` — Filter storage settings before saving (DYNAMIC)
672
-
673
- * **When it runs:** Dynamic filter applied just before storage driver settings are saved.
674
- * **Source:** `BaseStorageDriver.php` (line 152)
675
-
676
- #### Parameters:
677
- * `$settings` *(array)* — New settings array
678
- * `$oldSettings` *(array)* — Previous settings array
679
- * **Returns:** *(array)* — The modified settings array
680
-
681
- #### Usage Example:
682
- ```php
683
- // Filter S3 storage driver settings before saving to database
684
- add_filter('fluent_cart/storage/storage_settings_before_update_s3', function ($settings, $oldSettings) {
685
- // Preserve existing S3 secret key if omitted in update request
686
- if (empty($settings['secret_key']) && !empty($oldSettings['secret_key'])) {
687
- $settings['secret_key'] = $oldSettings['secret_key'];
688
- }
689
- return $settings;
690
- }, 10, 2);
691
- ```
692
-
693
- ---
694
-
695
- ## Localization & Address
696
-
697
- ### `country_state_options`
698
- `fluent_cart/country_state_options` — Filter country and state options
699
-
700
- * **When it runs:** Applied when retrieving country and state dropdown options for address forms.
701
- * **Source:** `LocalizationManager.php` (line 425)
702
-
703
- #### Parameters:
704
- * `$options` *(array)* — Country/state options array
705
- * **Returns:** *(array)* — The modified options array
706
-
707
- #### Usage Example:
708
- ```php
709
- // Filter country and state dropdown options array for address forms
710
- add_filter('fluent_cart/country_state_options', function ($options) {
711
- // Exclude invalid country code XX from countries dropdown list
712
- unset($options['countries']['XX']);
713
- return $options;
714
- });
715
- ```
716
-
717
- ---
718
-
719
- ### `address/postcode/format`
720
- `fluent_cart/address/postcode/format` — Filter postcode formatting
721
-
722
- * **When it runs:** Applied when formatting a postcode value, typically during address validation.
723
- * **Source:** `PostcodeVerification.php` (line 53)
724
-
725
- #### Parameters:
726
- * `$postcode` *(string)* — Trimmed postcode value
727
- * `$country` *(string)* — Country code (ISO 3166-1 alpha-2)
728
- * **Returns:** *(string)* — The formatted postcode string
729
-
730
- #### Usage Example:
731
- ```php
732
- // Filter formatted postcode string value during verification
733
- add_filter('fluent_cart/address/postcode/format', function ($postcode, $country) {
734
- // Format UK postcode with space delimiter
735
- if ($country === 'GB' && strlen($postcode) > 3 && strpos($postcode, ' ') === false) {
736
- return substr($postcode, 0, -3) . ' ' . substr($postcode, -3);
737
- }
738
- return $postcode;
739
- }, 10, 2);
740
- ```
741
-
742
- ---
743
-
744
- ### `address/postcode/is_valid`
745
- `fluent_cart/address/postcode/is_valid` — Filter postcode validation result
746
-
747
- * **When it runs:** Applied after postcode validation to enforce custom validation rules.
748
- * **Source:** `PostcodeVerification.php` (line 154)
749
-
750
- #### Parameters:
751
- * `$valid` *(bool)* — Whether postcode is valid
752
- * `$postcode` *(string)* — Postcode being validated
753
- * `$country` *(string)* — Country code (ISO 3166-1 alpha-2)
754
- * **Returns:** *(bool)* — The modified validation result
755
-
756
- #### Usage Example:
757
- ```php
758
- // Filter postcode validity verification result boolean
759
- add_filter('fluent_cart/address/postcode/is_valid', function ($valid, $postcode, $country) {
760
- // Validate 5-digit numeric postcode regex for custom country XX
761
- if ($country === 'XX') {
762
- return preg_match('/^\d{5}$/', $postcode) === 1;
763
- }
764
- return $valid;
765
- }, 10, 3);
766
- ```
767
-
768
- ---
769
-
770
- ### `util/countries` (legacy)
771
- `fluent-cart/util/countries` — Filter the country list
772
-
773
- * **When it runs:** Applied when retrieving full list of countries. Note hyphenated prefix (`fluent-cart/`).
774
- * **Source:** `Helper.php` (line 1140)
775
-
776
- #### Parameters:
777
- * `$options` *(array)* — Array of country code => country name pairs
778
- * **Returns:** *(array)* — The modified country list array
779
-
780
- #### Usage Example:
781
- ```php
782
- // Filter global country list array (legacy hyphenated hook name)
783
- add_filter('fluent-cart/util/countries', function ($options) {
784
- // Restrict countries list to US, CA, GB, and AU
785
- return array_intersect_key($options, array_flip(['US', 'CA', 'GB', 'AU']));
786
- });
787
- ```
788
-
789
- ---
790
-
791
- ## Templates & Frontend
792
-
793
- ### `template/disable_taxonomy_fallback`
794
- `fluent_cart/template/disable_taxonomy_fallback` — Disable taxonomy fallback template
795
-
796
- * **When it runs:** Controls whether taxonomy fallback template should be disabled (default: `false`).
797
- * **Source:** `TemplateLoader.php` (line 113)
798
-
799
- #### Parameters:
800
- * `$disable` *(bool)* — Whether to disable taxonomy fallback
801
- * **Returns:** *(bool)* — The modified boolean value
802
-
803
- #### Usage Example:
804
- ```php
805
- // Filter whether to disable taxonomy fallback template rendering
806
- add_filter('fluent_cart/template/disable_taxonomy_fallback', function ($disable) {
807
- // Disable taxonomy template fallback when custom theme template is active
808
- return true;
809
- });
810
- ```
811
-
812
- ---
813
-
814
- ### `has_block_template`
815
- `fluent_cart/has_block_template` — Filter block template existence check
816
-
817
- * **When it runs:** Applied when checking if block template exists for current page.
818
- * **Source:** `TemplateLoader.php` (line 193)
819
-
820
- #### Parameters:
821
- * `$hasTemplate` *(bool)* — Whether a block template exists
822
- * **Returns:** *(bool)* — The modified boolean result
823
-
824
- #### Usage Example:
825
- ```php
826
- // Filter block template existence check result for current page
827
- add_filter('fluent_cart/has_block_template', function ($hasTemplate) {
828
- // Force classic template rendering by returning false
829
- return false;
830
- });
831
- ```
832
-
833
- ---
834
-
835
- ### `template_loader_files`
836
- `fluent_cart/template_loader_files` — Filter template files to load
837
-
838
- * **When it runs:** Applied when determining which template files should be loaded for current request.
839
- * **Source:** `TemplateLoader.php` (line 206)
840
-
841
- #### Parameters:
842
- * `$files` *(array)* — Array of template file paths (default: `[]`)
843
- * **Returns:** *(array)* — The modified template files array
844
-
845
- #### Usage Example:
846
- ```php
847
- // Filter array of template file paths loaded for request
848
- add_filter('fluent_cart/template_loader_files', function ($files) {
849
- // Append custom stylesheet theme template file path
850
- $files[] = get_stylesheet_directory() . '/fluent-cart/custom-template.php';
851
- return $files;
852
- });
853
- ```
854
-
855
- ---
856
-
857
- ### `template_path`
858
- `fluent_cart/template_path` — Filter theme template path
859
-
860
- * **When it runs:** Controls directory path within a theme where FluentCart template overrides are located (default: `'fluent-cart/'`).
861
- * **Source:** `TemplateLoader.php` (line 248)
862
-
863
- #### Parameters:
864
- * `$path` *(string)* — Template directory path
865
- * **Returns:** *(string)* — The modified template path
866
-
867
- #### Usage Example:
868
- ```php
869
- // Filter theme directory path storing FluentCart template overrides
870
- add_filter('fluent_cart/template_path', function ($path) {
871
- // Override template overrides directory path in active theme
872
- return 'my-store/templates/';
873
- });
874
- ```
875
-
876
- ---
877
-
878
- ### `fluent_cart_template_part_content`
879
- `fluent_cart_template_part_content` — Filter template part content
880
-
881
- * **When it runs:** Applied to template part content before rendering.
882
- * **Source:** `ProductModalTemplatePart.php` (line 245)
883
-
884
- #### Parameters:
885
- * `$content` *(string)* — Template part content string
886
- * `$slug` *(string)* — Template part slug
887
- * `$args` *(array)* — Template arguments
888
- * **Returns:** *(string)* — The modified content string
889
-
890
- #### Usage Example:
891
- ```php
892
- // Filter template part content string before rendering
893
- add_filter('fluent_cart_template_part_content', function ($content, $slug, $args) {
894
- // Wrap product card template part HTML in custom container div
895
- if ($slug === 'product-card') {
896
- $content = '<div class="custom-wrapper">' . $content . '</div>';
897
- }
898
- return $content;
899
- }, 10, 3);
900
- ```
901
-
902
- ---
903
-
904
- ### `fluent_cart_template_part_content_{$slug}`
905
- `fluent_cart_template_part_content_{$slug}` — Filter template part content by slug (DYNAMIC)
906
-
907
- * **When it runs:** Dynamic filter applied to a specific template part's content.
908
- * **Source:** `ProductModalTemplatePart.php` (line 246)
909
-
910
- #### Parameters:
911
- * `$content` *(string)* — Template part content string
912
- * `$args` *(array)* — Template arguments
913
- * **Returns:** *(string)* — The modified content string
914
-
915
- #### Usage Example:
916
- ```php
917
- // Filter product card template part content by slug
918
- add_filter('fluent_cart_template_part_content_product-card', function ($content, $args) {
919
- // Append New badge HTML element to product card content
920
- $content .= '<span class="badge">New</span>';
921
- return $content;
922
- }, 10, 2);
923
- ```
924
-
925
- ---
926
-
927
- ### `fluent_cart_template_part_output`
928
- `fluent_cart_template_part_output` — Filter template part output
929
-
930
- * **When it runs:** Applied to final rendered output of a template part.
931
- * **Source:** `ProductModalTemplatePart.php` (line 252)
932
-
933
- #### Parameters:
934
- * `$output` *(string)* — Rendered template part output HTML
935
- * **Returns:** *(string)* — The modified output string
936
-
937
- #### Usage Example:
938
- ```php
939
- // Filter final rendered output string of template part
940
- add_filter('fluent_cart_template_part_output', function ($output) {
941
- // Minify rendered template part output whitespace
942
- return preg_replace('/\s+/', ' ', $output);
943
- });
944
- ```
945
-
946
- ---
947
-
948
- ### `fluent_cart_template_part_output_{$slug}`
949
- `fluent_cart_template_part_output_{$slug}` — Filter template part output by slug (DYNAMIC)
950
-
951
- * **When it runs:** Dynamic filter applied to final rendered output of a specific template part.
952
- * **Source:** `ProductModalTemplatePart.php` (line 253)
953
-
954
- #### Parameters:
955
- * `$output` *(string)* — Rendered output HTML
956
- * **Returns:** *(string)* — The modified output string
957
-
958
- #### Usage Example:
959
- ```php
960
- // Filter final output string of product modal template part
961
- add_filter('fluent_cart_template_part_output_product-modal', function ($output) {
962
- // Inject custom tracking data attribute into modal container div
963
- return str_replace('<div class="fct-modal"', '<div class="fct-modal" data-tracking="true"', $output);
964
- });
965
- ```
966
-
967
- ---
968
-
969
- ### `buttons/enable_floating_cart_button`
970
- `fluent_cart/buttons/enable_floating_cart_button` — Filter floating cart button visibility
971
-
972
- * **When it runs:** Controls whether floating cart button is displayed on frontend (default: `true`).
973
- * **Source:** `app/Hooks/Cart/CartLoader.php` (line 41)
974
-
975
- #### Parameters:
976
- * `$enabled` *(bool)* — Whether floating cart button is enabled
977
- * **Returns:** *(bool)* — The modified boolean value
978
-
979
- #### Usage Example:
980
- ```php
981
- // Filter frontend floating cart button visibility toggle
982
- add_filter('fluent_cart/buttons/enable_floating_cart_button', function ($enabled) {
983
- // Disable floating cart button on landing page
984
- if (is_page('landing-page')) {
985
- return false;
986
- }
987
- return $enabled;
988
- });
989
- ```
990
-
991
- ---
992
-
993
- ## Widgets & Dashboard
994
-
995
- ### `{$widgetName}`
996
- `fluent_cart/{$widgetName}` — Filter widget data by name (DYNAMIC)
997
-
998
- * **When it runs:** Dynamic filter applied when dashboard widget retrieves its data.
999
- * **Source:** `app/Services/Widgets/BaseWidget.php` (line 16)
1000
-
1001
- #### Parameters:
1002
- * `$widgetData` *(mixed)* — Widget data array returned by `widgetData()`
1003
- * **Returns:** *(mixed)* — The modified widget data
1004
-
1005
- #### Usage Example:
1006
- ```php
1007
- // Filter dashboard revenue widget data array dynamically
1008
- add_filter('fluent_cart/revenue_widget', function ($widgetData) {
1009
- // Inject calculated custom metric value into revenue widget data
1010
- $widgetData['custom_metric'] = calculate_custom_metric();
1011
- return $widgetData;
1012
- });
1013
- ```
1014
-
1015
- ---
1016
-
1017
- ### `widgets/{$filter}`
1018
- `fluent_cart/widgets/{$filter}` — Filter widget data by filter key (DYNAMIC)
1019
-
1020
- * **When it runs:** Dynamic filter applied when retrieving widget data for filter key in widgets controller.
1021
- * **Source:** `WidgetsController.php` (line 36)
1022
-
1023
- #### Parameters:
1024
- * `$result` *(array)* — Widget result data array (default: `[]`)
1025
- * `$data` *(array)* — Request data array
1026
- * **Returns:** *(array)* — The modified widget data array
1027
-
1028
- #### Usage Example:
1029
- ```php
1030
- // Filter sales overview widget chart data array dynamically
1031
- add_filter('fluent_cart/widgets/sales_overview', function ($result, $data) {
1032
- // Attach custom chart dataset structure to sales overview widget
1033
- $result['custom_chart'] = [
1034
- 'labels' => ['Jan', 'Feb', 'Mar'],
1035
- 'data' => [100, 200, 150],
1036
- ];
1037
- return $result;
1038
- }, 10, 2);
1039
- ```
1040
-
1041
- ---
1042
-
1043
- ### `promo_gateways`
1044
- `fluent_cart/promo_gateways` — Filter promotional gateways
1045
-
1046
- * **When it runs:** Applied when retrieving list of promotional payment gateways shown in admin.
1047
- * **Source:** `PromoGatewaysHandler.php` (line 36)
1048
-
1049
- #### Parameters:
1050
- * `$defaultGateways` *(array)* — Array of default promotional gateways
1051
- * **Returns:** *(array)* — The modified gateways array
1052
-
1053
- #### Usage Example:
1054
- ```php
1055
- // Filter promotional payment gateways list in admin panel
1056
- add_filter('fluent_cart/promo_gateways', function ($gateways) {
1057
- // Remove specific example gateway from promotional gateways
1058
- unset($gateways['example_gateway']);
1059
- return $gateways;
1060
- });
1061
- ```
1062
-
1063
- ---
1064
-
1065
- ### `addon_gateways`
1066
- `fluent_cart/addon_gateways` — Filter addon payment gateways
1067
-
1068
- * **When it runs:** Applied when retrieving list of addon payment gateways.
1069
- * **Source:** `AddonGatewaysHandler.php` (line 36)
1070
-
1071
- #### Parameters:
1072
- * `$defaultGateways` *(array)* — Array of default addon gateways
1073
- * **Returns:** *(array)* — The modified gateways array
1074
-
1075
- #### Usage Example:
1076
- ```php
1077
- // Filter addon payment gateways list array
1078
- add_filter('fluent_cart/addon_gateways', function ($gateways) {
1079
- // Register custom payment gateway addon definition
1080
- $gateways['custom_pay'] = [
1081
- 'title' => 'Custom Pay',
1082
- 'description' => 'Custom payment gateway addon',
1083
- 'is_active' => true,
1084
- ];
1085
- return $gateways;
1086
- });
1087
- ```
1088
-
1089
- ---
1090
-
1091
- ## Advanced List Filters
1092
-
1093
- ### `{$filter}_list_filter_query`
1094
- `fluent_cart/{$filter}_list_filter_query` — Filter list filter query (DYNAMIC)
1095
-
1096
- * **When it runs:** Dynamic filter applied when building database queries for filtered list pages (orders, customers, subscriptions, etc.).
1097
- * **Source:** `BaseFilter.php` (lines 962, 971)
1098
-
1099
- #### Parameters:
1100
- * `$query` *(\FluentCart\Framework\Database\Orm\Builder)* — Eloquent query builder instance
1101
- * **Returns:** *(\FluentCart\Framework\Database\Orm\Builder)* — The modified query builder
1102
-
1103
- #### Usage Example:
1104
- ```php
1105
- // Filter Eloquent query builder for admin orders list view
1106
- add_filter('fluent_cart/orders_list_filter_query', function ($query) {
1107
- // Restrict orders list query to orders created within last 30 days
1108
- $query->where('created_at', '>=', gmdate('Y-m-d H:i:s', strtotime('-30 days')));
1109
- return $query;
1110
- });
1111
- ```
1112
-
1113
- ---
1114
-
1115
- ### `{$filterName}_filter_options`
1116
- `fluent_cart/{$filterName}_filter_options` — Filter options for list page filters (DYNAMIC)
1117
-
1118
- * **When it runs:** Dynamic filter applied when retrieving available filter options for admin list pages.
1119
- * **Source:** `BaseFilter.php` (line 995)
1120
-
1121
- #### Parameters:
1122
- * `$options` *(array)* — Filter options array
1123
- * **Returns:** *(array)* — The modified filter options array
1124
-
1125
- #### Usage Example:
1126
- ```php
1127
- // Filter available filter dropdown options for orders list page
1128
- add_filter('fluent_cart/orders_filter_options', function ($options) {
1129
- // Inject custom status dropdown filter option for orders list page
1130
- $options['custom_status'] = [
1131
- 'label' => 'Custom Status',
1132
- 'type' => 'select',
1133
- 'options' => ['pending_review' => 'Pending Review'],
1134
- ];
1135
- return $options;
1136
- });
1137
- ```
1138
-
1139
- ---
1140
-
1141
- ### `{$filterName}_table_columns`
1142
- `fluent_cart/{$filterName}_table_columns` — Filter table columns for list pages (DYNAMIC)
1143
-
1144
- * **When it runs:** Dynamic filter applied when retrieving table column definitions for admin list pages.
1145
- * **Source:** `BaseFilter.php` (line 1038)
1146
-
1147
- #### Parameters:
1148
- * `$columns` *(array)* — Table column definitions array (default: `[]`)
1149
- * **Returns:** *(array)* — The modified columns array
1150
-
1151
- #### Usage Example:
1152
- ```php
1153
- // Filter table column definitions for admin orders list view
1154
- add_filter('fluent_cart/orders_table_columns', function ($columns) {
1155
- // Append custom field column definition to orders table
1156
- $columns['custom_field'] = [
1157
- 'label' => 'Custom Field',
1158
- 'sortable' => true,
1159
- 'width' => '120px',
1160
- ];
1161
- return $columns;
1162
- });
1163
- ```
1164
-
1165
- ---
1166
-
1167
- ### `advanced_filter_options_{$dataKey}`
1168
- `fluent_cart/advanced_filter_options_{$dataKey}` — Filter advanced filter options (DYNAMIC)
1169
-
1170
- * **When it runs:** Dynamic filter applied when retrieving options for advanced filter UI.
1171
- * **Source:** `AdvanceFilterController.php` (line 46)
1172
-
1173
- #### Parameters:
1174
- * `$options` *(array)* — Filter options array
1175
- * **Returns:** *(array)* — The modified options array
1176
-
1177
- #### Usage Example:
1178
- ```php
1179
- // Filter options array for advanced filter UI payment methods
1180
- add_filter('fluent_cart/advanced_filter_options_payment_methods', function ($options) {
1181
- // Append custom gateway option to advanced filter UI
1182
- $options[] = [
1183
- 'value' => 'custom_gateway',
1184
- 'label' => 'Custom Gateway',
1185
- ];
1186
- return $options;
1187
- });
1188
- ```
1189
-
1190
- ---
1191
-
1192
- ## Plugin Installer
1193
-
1194
- ### `outside_addon/handle_cdn_install`
1195
- `fluent_cart/outside_addon/handle_cdn_install` — Filter CDN addon installation
1196
-
1197
- * **When it runs:** Applied when attempting to install an addon from a CDN source. Return non-null value to handle installation manually.
1198
- * **Source:** `BackgroundInstaller.php` (line 143)
1199
-
1200
- #### Parameters:
1201
- * `$result` *(mixed)* — Installation result (default: `null`)
1202
- * **Returns:** *(mixed)* — The installation result, or `null` for default handling
1203
-
1204
- #### Usage Example:
1205
- ```php
1206
- // Intercept addon installation from CDN external source
1207
- add_filter('fluent_cart/outside_addon/handle_cdn_install', function ($result) {
1208
- // Handle custom CDN addon installation logic
1209
- if ($result === null) {
1210
- return ['success' => true, 'message' => 'Installed from custom CDN'];
1211
- }
1212
- return $result;
1213
- });
1214
- ```
1215
-
1216
- ---
1217
-
1218
- ### `outside_addon/handle_install`
1219
- `fluent_cart/outside_addon/handle_install` — Filter external addon installation
1220
-
1221
- * **When it runs:** Applied when installing an addon from an external source. Return non-null value to handle installation manually.
1222
- * **Source:** `BackgroundInstaller.php` (line 164)
1223
-
1224
- #### Parameters:
1225
- * `$result` *(mixed)* — Installation result (default: `null`)
1226
- * **Returns:** *(mixed)* — The installation result, or `null` for default handling
1227
-
1228
- #### Usage Example:
1229
- ```php
1230
- // Intercept external addon installation process
1231
- add_filter('fluent_cart/outside_addon/handle_install', function ($result) {
1232
- // Return success response payload for custom external addon installer
1233
- return ['success' => true, 'message' => 'Addon installed successfully'];
1234
- });
1235
- ```
1236
-
1237
- ---
1238
-
1239
- ## Pro: E-Invoicing
1240
-
1241
- ### `einvoice/buyer_vat_id` (Pro)
1242
- `fluent_cart/einvoice/buyer_vat_id` — Filter buyer VAT ID written to e-invoice
1243
-
1244
- * **When it runs:** Applied in `En16931InvoiceMapper` while mapping order to EN 16931 e-invoice (BT-48) XML. Requires Pro plugin.
1245
- * **Source:** `fluent-cart-pro/.../En16931InvoiceMapper.php` (line 154)
1246
-
1247
- #### Parameters:
1248
- * `$buyerVatId` *(string)* — Resolved buyer VAT identifier
1249
- * `$context` *(array)* — Context data (`['order' => Order]`)
1250
- * **Returns:** *(string)* — The buyer VAT identifier string to write
1251
-
1252
- #### Usage Example:
1253
- ```php
1254
- // Filter buyer VAT identification string written to EN 16931 e-invoice (Pro)
1255
- add_filter('fluent_cart/einvoice/buyer_vat_id', function ($buyerVatId, $context) {
1256
- // Prepend billing country code prefix to buyer VAT ID if omitted
1257
- $country = $context['order']->billing_address->country ?? '';
1258
- if ($country && strpos($buyerVatId, $country) !== 0) {
1259
- $buyerVatId = $country . $buyerVatId;
1260
- }
1261
-
1262
- return $buyerVatId;
1263
- }, 10, 2);
1264
- ```
1265
-
1266
- ---
1267
-
1268
- ### `einvoice/tax_category` (Pro)
1269
- `fluent_cart/einvoice/tax_category` — Filter EN 16931 VAT category for e-invoice line
1270
-
1271
- * **When it runs:** Applied in `En16931InvoiceMapper` after resolving EN 16931 VAT category for invoice line or shipping charge. Requires Pro plugin.
1272
- * **Source:** `fluent-cart-pro/.../En16931InvoiceMapper.php` (line 357)
1273
-
1274
- #### Parameters:
1275
- * `$resolved` *(array)* — Category data (`categoryCode`, `ratePercent`, `exemptionReasonCode`, `exemptionReasonText`)
1276
- * `$context` *(array)* — Context data (`['order' => Order, 'line' => LineItem|null]`)
1277
- * **Returns:** *(array)* — The modified VAT category data array
1278
-
1279
- #### Usage Example:
1280
- ```php
1281
- // Filter EN 16931 VAT tax category data for e-invoice line item (Pro)
1282
- add_filter('fluent_cart/einvoice/tax_category', function ($resolved, $context) {
1283
- // Force exempt category E for target product line post ID 123
1284
- if ($context['line'] && ($context['line']->post_id ?? 0) === 123) {
1285
- $resolved['categoryCode'] = 'E';
1286
- $resolved['ratePercent'] = 0.0;
1287
- $resolved['exemptionReasonCode'] = 'VATEX-EU-O';
1288
- $resolved['exemptionReasonText'] = 'Exempt supply';
1289
- }
1290
-
1291
- return $resolved;
1292
- }, 10, 2);
1293
- ```
1294
-
1295
- ---
1296
-
1297
- ## Pro: Licensing API
1298
-
1299
- ### `license/checking_error` (Pro)
1300
- `fluent_cart/license/checking_error` — Filter license check error response
1301
-
1302
- * **When it runs:** Applied when license check encounters an error to customize error response payload. Requires Pro plugin.
1303
- * **Source:** `LicenseApiHandler.php` (lines 45, 56)
1304
-
1305
- #### Parameters:
1306
- * `$error` *(array)* — Error response array
1307
- * **Returns:** *(array)* — Modified error response array
1308
-
1309
- #### Usage Example:
1310
- ```php
1311
- // Filter license verification error response array (Pro)
1312
- add_filter('fluent_cart/license/checking_error', function ($error) {
1313
- // Override license check error message string
1314
- $error['message'] = 'Please contact support for license verification.';
1315
- return $error;
1316
- });
1317
- ```
1318
-
1319
- ---
1320
-
1321
- ### `license/check_item_id` (Pro)
1322
- `fluent_cart/license/check_item_id` — Filter item ID validation during license check
1323
-
1324
- * **When it runs:** Controls whether item ID should be validated during license check API request (default: `true`). Requires Pro plugin.
1325
- * **Source:** `LicenseApiHandler.php` (line 54)
1326
-
1327
- #### Parameters:
1328
- * `$checkItemId` *(bool)* — Whether to check item ID
1329
- * **Returns:** *(bool)* — Modified boolean value
1330
-
1331
- #### Usage Example:
1332
- ```php
1333
- // Filter whether item ID is validated during license check API call (Pro)
1334
- add_filter('fluent_cart/license/check_item_id', function ($checkItemId) {
1335
- // Skip item ID check during license check API request
1336
- return false;
1337
- });
1338
- ```
1339
-
1340
- ---
1341
-
1342
- ### `license/check_license_response` (Pro)
1343
- `fluent_cart/license/check_license_response` — Filter license check API response
1344
-
1345
- * **When it runs:** Applied to license check API response before returning to client. Requires Pro plugin.
1346
- * **Source:** `LicenseApiHandler.php` (line 83)
1347
-
1348
- #### Parameters:
1349
- * `$returnData` *(array)* — License check response data array
1350
- * **Returns:** *(array)* — Modified response data array
1351
-
1352
- #### Usage Example:
1353
- ```php
1354
- // Filter license check API response payload before returning to client (Pro)
1355
- add_filter('fluent_cart/license/check_license_response', function ($returnData) {
1356
- // Append custom support URL string to license check API response
1357
- $returnData['support_url'] = 'https://example.com/support';
1358
- return $returnData;
1359
- });
1360
- ```
1361
-
1362
- ---
1363
-
1364
- ### `license/activate_license_response` (Pro)
1365
- `fluent_cart/license/activate_license_response` — Filter license activation API response
1366
-
1367
- * **When it runs:** Applied to license activation API response before returning to client. Requires Pro plugin.
1368
- * **Source:** `LicenseApiHandler.php` (lines 170, 274)
1369
-
1370
- #### Parameters:
1371
- * `$returnData` *(array)* — Activation response data array
1372
- * **Returns:** *(array)* — Modified response data array
1373
-
1374
- #### Usage Example:
1375
- ```php
1376
- // Filter license activation API response payload (Pro)
1377
- add_filter('fluent_cart/license/activate_license_response', function ($returnData) {
1378
- // Append activated_at timestamp string to license activation response
1379
- $returnData['activated_at'] = gmdate('Y-m-d H:i:s');
1380
- return $returnData;
1381
- });
1382
- ```
1383
-
1384
- ---
1385
-
1386
- ### `license/deactivate_license_response` (Pro)
1387
- `fluent_cart/license/deactivate_license_response` — Filter license deactivation API response
1388
-
1389
- * **When it runs:** Applied to license deactivation API response before returning to client. Requires Pro plugin.
1390
- * **Source:** `LicenseApiHandler.php` (line 356)
1391
-
1392
- #### Parameters:
1393
- * `$returnData` *(array)* — Deactivation response data array
1394
- * **Returns:** *(array)* — Modified response data array
1395
-
1396
- #### Usage Example:
1397
- ```php
1398
- // Filter license deactivation API response payload (Pro)
1399
- add_filter('fluent_cart/license/deactivate_license_response', function ($returnData) {
1400
- // Append deactivation notice text string to response
1401
- $returnData['notice'] = 'License deactivated. You can reactivate on another site.';
1402
- return $returnData;
1403
- });
1404
- ```
1405
-
1406
- ---
1407
-
1408
- ### `license/get_version_response` (Pro)
1409
- `fluent_cart/license/get_version_response` — Filter version check API response
1410
-
1411
- * **When it runs:** Applied to version check API response to modify changelog or update information. Requires Pro plugin.
1412
- * **Source:** `LicenseApiHandler.php` (line 463)
1413
-
1414
- #### Parameters:
1415
- * `$changeLogData` *(array)* — Version and changelog response data array
1416
- * **Returns:** *(array)* — Modified response data array
1417
-
1418
- #### Usage Example:
1419
- ```php
1420
- // Filter software update version check API response payload (Pro)
1421
- add_filter('fluent_cart/license/get_version_response', function ($changeLogData) {
1422
- // Append custom patch entry string to changelog section
1423
- $changeLogData['sections']['changelog'] .= "\n* Custom patch applied";
1424
- return $changeLogData;
1425
- });
1426
- ```
1427
-
1428
- ---
1429
-
1430
- ### `license/santized_url` (Pro)
1431
- `fluent_cart/license/santized_url` — Filter sanitized URL for license validation
1432
-
1433
- * **When it runs:** Applied when sanitizing site URL during license activation or validation. Requires Pro plugin.
1434
- * **Source:** `LicenseHelper.php` (line 36)
1435
-
1436
- #### Parameters:
1437
- * `$url` *(string)* — Sanitized URL string
1438
- * `$originalUrl` *(string)* — Original URL before sanitization
1439
- * **Returns:** *(string)* — Modified sanitized URL string
1440
-
1441
- #### Usage Example:
1442
- ```php
1443
- // Filter sanitized URL string used during license validation (Pro)
1444
- add_filter('fluent_cart/license/santized_url', function ($url, $originalUrl) {
1445
- // Strip www subdomain prefix from sanitized site URL
1446
- return str_replace('://www.', '://', $url);
1447
- }, 10, 2);
1448
- ```
1449
-
1450
- ---
1451
-
1452
- ## Pro: License Validation & Staging
1453
-
1454
- ### `fluent_cart_sl/is_local_site` (Pro)
1455
- `fluent_cart_sl/is_local_site` — Filter local/staging site detection
1456
-
1457
- * **When it runs:** Applied when determining if current site is local or staging for licensing purposes. Requires Pro plugin.
1458
- * **Source:** `fluent-cart-pro/.../LicenseSite.php` (line 69)
1459
-
1460
- #### Parameters:
1461
- * `$isLocal` *(bool)* — Whether site is detected as local
1462
- * `$context` *(array)* — Context data (`['url' => string, 'site' => string]`)
1463
- * **Returns:** *(bool)* — Modified detection result boolean
1464
-
1465
- #### Usage Example:
1466
- ```php
1467
- // Filter local or staging site detection boolean for licensing (Pro)
1468
- add_filter('fluent_cart_sl/is_local_site', function ($isLocal, $context) {
1469
- // Mark URLs containing .staging. as local staging sites
1470
- if (str_contains($context['url'], '.staging.')) {
1471
- return true;
1472
- }
1473
- return $isLocal;
1474
- }, 10, 2);
1475
- ```
1476
-
1477
- ---
1478
-
1479
- ### `license/staging_subdomain_patterns` (Pro)
1480
- `fluent_cart/license/staging_subdomain_patterns` — Filter staging subdomain patterns
1481
-
1482
- * **When it runs:** Applied when checking if URL matches known staging subdomain patterns. Requires Pro plugin.
1483
- * **Source:** `LicenseHelper.php` (line 619)
1484
-
1485
- #### Parameters:
1486
- * `$patterns` *(array)* — Array of subdomain patterns indicating staging sites
1487
- * **Returns:** *(array)* — Modified patterns array
1488
-
1489
- #### Usage Example:
1490
- ```php
1491
- // Filter staging subdomain regex patterns array for licensing (Pro)
1492
- add_filter('fluent_cart/license/staging_subdomain_patterns', function ($patterns) {
1493
- // Append dev- and test- subdomain prefixes to staging patterns list
1494
- $patterns[] = 'dev-';
1495
- $patterns[] = 'test-';
1496
- return $patterns;
1497
- });
1498
- ```
1499
-
1500
- ---
1501
-
1502
- ### `license/staging_subfolder_patterns` (Pro)
1503
- `fluent_cart/license/staging_subfolder_patterns` — Filter staging subfolder patterns
1504
-
1505
- * **When it runs:** Applied when checking if URL matches known staging subfolder patterns. Requires Pro plugin.
1506
- * **Source:** `LicenseHelper.php` (line 620)
1507
-
1508
- #### Parameters:
1509
- * `$patterns` *(array)* — Array of subfolder patterns indicating staging sites
1510
- * **Returns:** *(array)* — Modified patterns array
1511
-
1512
- #### Usage Example:
1513
- ```php
1514
- // Filter staging subfolder path patterns array for licensing (Pro)
1515
- add_filter('fluent_cart/license/staging_subfolder_patterns', function ($patterns) {
1516
- // Append /staging/ and /test-site/ subfolders to staging patterns
1517
- $patterns[] = '/staging/';
1518
- $patterns[] = '/test-site/';
1519
- return $patterns;
1520
- });
1521
- ```
1522
-
1523
- ---
1524
-
1525
- ### `license/staging_domains` (Pro)
1526
- `fluent_cart/license/staging_domains` — Filter hosting provider staging domains
1527
-
1528
- * **When it runs:** Applied when checking if URL belongs to known hosting provider staging domain. Requires Pro plugin.
1529
- * **Source:** `LicenseHelper.php` (line 621)
1530
-
1531
- #### Parameters:
1532
- * `$domains` *(array)* — Array of hosting provider staging domain patterns
1533
- * **Returns:** *(array)* — Modified domains array
1534
-
1535
- #### Usage Example:
1536
- ```php
1537
- // Filter hosting provider staging domain patterns array (Pro)
1538
- add_filter('fluent_cart/license/staging_domains', function ($domains) {
1539
- // Append custom hosting provider staging domain patterns
1540
- $domains[] = 'mystaginghost.com';
1541
- $domains[] = 'preview.myhost.io';
1542
- return $domains;
1543
- });
1544
- ```
1545
-
1546
- ---
1547
-
1548
- ### `license/is_staging_site_result` (Pro)
1549
- `fluent_cart/license/is_staging_site_result` — Filter final staging site detection result
1550
-
1551
- * **When it runs:** Applied after all staging detection checks to provide final boolean result (default: `false`). Requires Pro plugin.
1552
- * **Source:** `LicenseHelper.php` (line 657)
1553
-
1554
- #### Parameters:
1555
- * `$isStaging` *(bool)* — Whether site is detected as staging
1556
- * `$url` *(string)* — Site URL being checked
1557
- * **Returns:** *(bool)* — Modified staging detection result
1558
-
1559
- #### Usage Example:
1560
- ```php
1561
- // Filter final staging site detection boolean result (Pro)
1562
- add_filter('fluent_cart/license/is_staging_site_result', function ($isStaging, $url) {
1563
- // Override staging detection for specific target domain string
1564
- if (str_contains($url, 'mycompany-staging.com')) {
1565
- return true;
1566
- }
1567
- return $isStaging;
1568
- }, 10, 2);
1569
- ```
1570
-
1571
- ---
1572
-
1573
- ## Pro: License Configuration
1574
-
1575
- ### `license/validity_by_variation` (Pro)
1576
- `fluent_cart/license/validity_by_variation` — Filter license validity per variation
1577
-
1578
- * **When it runs:** Applied when determining license validity settings for a specific product variation. Requires Pro plugin.
1579
- * **Source:** `ProductLicenseController.php` (line 74)
1580
-
1581
- #### Parameters:
1582
- * `$validity` *(array)* — Validity settings array (`duration`, `unit`)
1583
- * `$context` *(array)* — Context data (`['variation' => ProductVariation]`)
1584
- * **Returns:** *(array)* — The modified validity settings array
1585
-
1586
- #### Usage Example:
1587
- ```php
1588
- // Filter license validity settings per product variation (Pro)
1589
- add_filter('fluent_cart/license/validity_by_variation', function ($validity, $context) {
1590
- // Apply 365-day license validity for premium variation slug
1591
- $variation = $context['variation'];
1592
- if ($variation->slug === 'premium') {
1593
- $validity['duration'] = 365;
1594
- $validity['unit'] = 'days';
1595
- }
1596
- return $validity;
1597
- }, 10, 2);
1598
- ```
1
+ # Filter Hooks: Integrations & Advanced
2
+
3
+ All filters related to external integrations, file storage, templates, License management, and advanced features.
4
+
5
+ ---
6
+
7
+ ## Integration Actions & Feeds
8
+
9
+ ### `order_integrations`
10
+ `fluent_cart/integration/order_integrations` — Filter all registered order integrations
11
+
12
+ * **When it runs:** Applied when retrieving the list of all registered order integrations across event listeners, controllers, settings, and addons.
13
+ * **Source:** `IntegrationEventListener.php` (lines 54, 247, 386), `IntegrationController.php` (lines 96, 150), `ProductIntegrationsController.php` (lines 18, 48), `GlobalIntegrationSettings.php` (line 84)
14
+
15
+ #### Parameters:
16
+ * `$integrations` *(array)* — Array of registered integrations (`MailChimp`, `FluentCRM`, etc.)
17
+ * **Returns:** *(array)* — The modified integrations array
18
+
19
+ #### Usage Example:
20
+ ```php
21
+ // Filter array of registered order integrations in FluentCart
22
+ add_filter('fluent_cart/integration/order_integrations', function ($integrations) {
23
+ // Add custom CRM integration definition array
24
+ $integrations['custom_crm'] = [
25
+ 'title' => 'Custom CRM',
26
+ 'logo' => 'https://example.com/crm-logo.png',
27
+ 'enabled' => true,
28
+ ];
29
+ return $integrations;
30
+ });
31
+ ```
32
+
33
+ ---
34
+
35
+ ### `run_all_actions_on_async`
36
+ `fluent_cart/integration/run_all_actions_on_async` — Force all integration actions to run asynchronously
37
+
38
+ * **When it runs:** Controls whether integration actions should be dispatched asynchronously instead of immediately during order processing.
39
+ * **Source:** `IntegrationEventListener.php` (line 145)
40
+
41
+ #### Parameters:
42
+ * `$async` *(bool)* — Whether to force async execution (default: `false`)
43
+ * `$order` *(\FluentCart\App\Models\Order)* — The order model instance
44
+ * `$hook` *(string)* — The integration hook being fired
45
+ * **Returns:** *(bool)* — Whether to run actions asynchronously
46
+
47
+ #### Usage Example:
48
+ ```php
49
+ // Force integration actions to dispatch asynchronously for large orders
50
+ add_filter('fluent_cart/integration/run_all_actions_on_async', function ($async, $order, $hook) {
51
+ // Force async execution for orders exceeding $1,000 total
52
+ if ($order->total > 100000) {
53
+ return true;
54
+ }
55
+ return $async;
56
+ }, 10, 3);
57
+ ```
58
+
59
+ ---
60
+
61
+ ### `global_notification_types`
62
+ `fluent_cart/integration/global_notification_types` — Filter available notification types
63
+
64
+ * **When it runs:** Applied when retrieving the list of available global notification types for integrations.
65
+ * **Source:** `GlobalIntegrationSettings.php` (line 119)
66
+
67
+ #### Parameters:
68
+ * `$types` *(array)* — Array of notification types (`email`, etc.)
69
+ * **Returns:** *(array)* — The modified notification types array
70
+
71
+ #### Usage Example:
72
+ ```php
73
+ // Filter available global integration notification types array
74
+ add_filter('fluent_cart/integration/global_notification_types', function ($types) {
75
+ // Append SMS notification type definition
76
+ $types['sms'] = [
77
+ 'title' => 'SMS Notification',
78
+ 'description' => 'Send SMS notifications on order events',
79
+ ];
80
+ return $types;
81
+ });
82
+ ```
83
+
84
+ ---
85
+
86
+ ### `global_notification_feed_{$feed_key}`
87
+ `fluent_cart/integration/global_notification_feed_{$feed_key}` — Filter notification feed data (DYNAMIC)
88
+
89
+ * **When it runs:** Dynamic filter applied when retrieving notification feed data for a specific feed key.
90
+ * **Source:** `GlobalIntegrationSettings.php` (line 151)
91
+
92
+ #### Parameters:
93
+ * `$feedData` *(array)* — The notification feed data array
94
+ * **Returns:** *(array)* — The modified feed data array
95
+
96
+ #### Usage Example:
97
+ ```php
98
+ // Filter notification feed data array for email alerts feed
99
+ add_filter('fluent_cart/integration/global_notification_feed_email_alerts', function ($feedData) {
100
+ // Append additional admin email recipient to feed data
101
+ $feedData['recipients'][] = 'extra-admin@example.com';
102
+ return $feedData;
103
+ });
104
+ ```
105
+
106
+ ---
107
+
108
+ ### `get_global_integration_actions`
109
+ `fluent_cart/integration/get_global_integration_actions` — Filter global integration actions
110
+
111
+ * **When it runs:** Applied when retrieving available global integration actions triggered by order events.
112
+ * **Source:** `GlobalIntegrationActionHandler.php` (line 22)
113
+
114
+ #### Parameters:
115
+ * `$actions` *(array)* — Array of integration actions (default: `[]`)
116
+ * **Returns:** *(array)* — The modified integration actions array
117
+
118
+ #### Usage Example:
119
+ ```php
120
+ // Filter available global integration actions list
121
+ add_filter('fluent_cart/integration/get_global_integration_actions', function ($actions) {
122
+ // Append custom webhook action definition to integration actions
123
+ $actions['custom_webhook'] = [
124
+ 'title' => 'Fire Custom Webhook',
125
+ 'enabled' => true,
126
+ ];
127
+ return $actions;
128
+ });
129
+ ```
130
+
131
+ ---
132
+
133
+ ### `notifying_async_{$feedKey}`
134
+ `fluent_cart/integration/notifying_async_{$feedKey}` — Control async notification per feed (DYNAMIC)
135
+
136
+ * **When it runs:** Dynamic filter controlling whether a specific notification feed is processed asynchronously (default: `true`).
137
+ * **Source:** `GlobalNotificationHandler.php` (line 104)
138
+
139
+ #### Parameters:
140
+ * `$async` *(bool)* — Whether to process notification asynchronously (default: `true`)
141
+ * **Returns:** *(bool)* — Whether to use async processing
142
+
143
+ #### Usage Example:
144
+ ```php
145
+ // Control async notification dispatch for email alerts feed
146
+ add_filter('fluent_cart/integration/notifying_async_email_alerts', function ($async) {
147
+ // Force synchronous processing for email alerts notification feed
148
+ return false;
149
+ });
150
+ ```
151
+
152
+ ---
153
+
154
+ ### `webhook/payload` (Pro)
155
+ `fluent_cart/webhook/payload` — Filter webhook payload before sending
156
+
157
+ * **When it runs:** Applied to webhook payload body after construction, before encoding and dispatching to external endpoint. Requires Pro plugin.
158
+ * **Source:** `fluent-cart-pro/.../WebhookConnect.php` (line 251)
159
+
160
+ #### Parameters:
161
+ * `$payloadBody` *(array)* — Payload body data array
162
+ * `$context` *(array)* — Context data (`['order' => Order, 'feed' => array, 'event_data' => array]`)
163
+ * **Returns:** *(array)* — The modified payload body array
164
+
165
+ #### Usage Example:
166
+ ```php
167
+ // Filter webhook payload array before sending to external endpoint (Pro)
168
+ add_filter('fluent_cart/webhook/payload', function ($payloadBody, $context) {
169
+ // Append custom tracking metadata to payload body
170
+ $payloadBody['custom_meta'] = [
171
+ 'source' => 'fluentcart',
172
+ 'timestamp' => gmdate('Y-m-d H:i:s')
173
+ ];
174
+
175
+ // Remove customer email address from webhook payload
176
+ unset($payloadBody['customer']['email']);
177
+
178
+ return $payloadBody;
179
+ }, 10, 2);
180
+ ```
181
+
182
+ ---
183
+
184
+ ## Integration Settings & Configuration
185
+
186
+ ### `global_integration_settings_{$key}`
187
+ `fluent_cart/integration/global_integration_settings_{$key}` — Filter integration settings (DYNAMIC)
188
+
189
+ * **When it runs:** Dynamic filter applied when retrieving settings for a specific integration (e.g. `mailchimp`, `zapier`).
190
+ * **Source:** `GlobalIntegrationSettings.php` (line 24)
191
+
192
+ #### Parameters:
193
+ * `$settings` *(array)* — Integration settings array (default: `[]`)
194
+ * **Returns:** *(array)* — The modified settings array
195
+
196
+ #### Usage Example:
197
+ ```php
198
+ // Filter integration settings array for MailChimp integration
199
+ add_filter('fluent_cart/integration/global_integration_settings_mailchimp', function ($settings) {
200
+ // Override MailChimp API key from environment constant if defined
201
+ $settings['api_key'] = defined('MAILCHIMP_API_KEY') ? MAILCHIMP_API_KEY : $settings['api_key'];
202
+ return $settings;
203
+ });
204
+ ```
205
+
206
+ ---
207
+
208
+ ### `global_integration_fields_{$key}`
209
+ `fluent_cart/integration/global_integration_fields_{$key}` — Filter integration field definitions (DYNAMIC)
210
+
211
+ * **When it runs:** Dynamic filter applied when retrieving field definitions for an integration configuration form.
212
+ * **Source:** `GlobalIntegrationSettings.php` (line 25)
213
+
214
+ #### Parameters:
215
+ * `$fields` *(array)* — Field definitions array (default: `[]`)
216
+ * **Returns:** *(array)* — The modified field definitions array
217
+
218
+ #### Usage Example:
219
+ ```php
220
+ // Filter integration configuration form fields for MailChimp
221
+ add_filter('fluent_cart/integration/global_integration_fields_mailchimp', function ($fields) {
222
+ // Append double opt-in checkbox field definition
223
+ $fields[] = [
224
+ 'key' => 'double_optin',
225
+ 'label' => 'Enable Double Opt-in',
226
+ 'type' => 'checkbox',
227
+ ];
228
+ return $fields;
229
+ });
230
+ ```
231
+
232
+ ---
233
+
234
+ ### `get_integration_defaults_{$name}`
235
+ `fluent_cart/integration/get_integration_defaults_{$name}` — Filter integration defaults (DYNAMIC)
236
+
237
+ * **When it runs:** Dynamic filter applied when retrieving default settings for a specific integration.
238
+ * **Source:** `GlobalIntegrationSettings.php` (lines 199, 201)
239
+
240
+ #### Parameters:
241
+ * `$defaults` *(array)* — Default settings values array
242
+ * **Returns:** *(array)* — The modified defaults array
243
+
244
+ #### Usage Example:
245
+ ```php
246
+ // Filter default settings values for MailChimp integration
247
+ add_filter('fluent_cart/integration/get_integration_defaults_mailchimp', function ($defaults) {
248
+ // Set default audience list ID and tag array
249
+ $defaults['list_id'] = 'default_list_123';
250
+ $defaults['tags'] = ['fluentcart-customer'];
251
+ return $defaults;
252
+ });
253
+ ```
254
+
255
+ ---
256
+
257
+ ### `get_integration_settings_fields_{$name}`
258
+ `fluent_cart/integration/get_integration_settings_fields_{$name}` — Filter integration settings fields (DYNAMIC)
259
+
260
+ * **When it runs:** Dynamic filter applied when retrieving settings field definitions for a specific integration.
261
+ * **Source:** `GlobalIntegrationSettings.php` (lines 204, 276), `IntegrationHelper.php` (line 27)
262
+
263
+ #### Parameters:
264
+ * `$fields` *(array)* — Field definitions array (default: `[]`)
265
+ * **Returns:** *(array)* — The modified field definitions array
266
+
267
+ #### Usage Example:
268
+ ```php
269
+ // Filter settings form field definitions for Zapier integration
270
+ add_filter('fluent_cart/integration/get_integration_settings_fields_zapier', function ($fields) {
271
+ // Append webhook URL input field definition
272
+ $fields[] = [
273
+ 'key' => 'webhook_url',
274
+ 'label' => 'Webhook URL',
275
+ 'type' => 'url',
276
+ 'required' => true,
277
+ 'placeholder' => 'https://hooks.zapier.com/...',
278
+ ];
279
+ return $fields;
280
+ });
281
+ ```
282
+
283
+ ---
284
+
285
+ ### `save_integration_values_{$name}`
286
+ `fluent_cart/integration/save_integration_values_{$name}` — Filter before saving integration data (DYNAMIC)
287
+
288
+ * **When it runs:** Dynamic filter applied just before integration settings are saved to database.
289
+ * **Source:** `GlobalIntegrationSettings.php` (line 248)
290
+
291
+ #### Parameters:
292
+ * `$integration` *(\FluentCart\App\Models\Meta)* — Meta model instance containing integration data
293
+ * **Returns:** *(\FluentCart\App\Models\Meta)* — The modified Meta model instance
294
+
295
+ #### Usage Example:
296
+ ```php
297
+ // Filter Meta model instance before saving MailChimp integration data
298
+ add_filter('fluent_cart/integration/save_integration_values_mailchimp', function ($integration) {
299
+ // Encrypt API key field value before persisting to database
300
+ $value = $integration->value;
301
+ if (!empty($value['api_key'])) {
302
+ $value['api_key_encrypted'] = encrypt($value['api_key']);
303
+ }
304
+ $integration->value = $value;
305
+ return $integration;
306
+ });
307
+ ```
308
+
309
+ ---
310
+
311
+ ### `get_integration_merge_fields_{$name}`
312
+ `fluent_cart/integration/get_integration_merge_fields_{$name}` — Filter integration merge/mapping fields (DYNAMIC)
313
+
314
+ * **When it runs:** Dynamic filter applied when retrieving merge fields for mapping FluentCart data to external service fields.
315
+ * **Source:** `GlobalIntegrationSettings.php` (line 369)
316
+
317
+ #### Parameters:
318
+ * `$list` *(array)* — Merge fields list array
319
+ * `$listId` *(string)* — Audience or list identifier
320
+ * **Returns:** *(array)* — The modified merge fields array
321
+
322
+ #### Usage Example:
323
+ ```php
324
+ // Filter integration merge mapping fields for MailChimp
325
+ add_filter('fluent_cart/integration/get_integration_merge_fields_mailchimp', function ($list, $listId) {
326
+ // Append Company Name field to merge fields mapping list
327
+ $list[] = [
328
+ 'key' => 'COMPANY',
329
+ 'label' => 'Company Name',
330
+ 'type' => 'text',
331
+ ];
332
+ return $list;
333
+ }, 10, 2);
334
+ ```
335
+
336
+ ---
337
+
338
+ ### `integration_options_{$key}`
339
+ `fluent_cart/integration/integration_options_{$key}` — Filter dynamic integration options (DYNAMIC)
340
+
341
+ * **When it runs:** Dynamic filter applied when retrieving option values for integration dropdown or selection fields.
342
+ * **Source:** `IntegrationController.php` (line 302)
343
+
344
+ #### Parameters:
345
+ * `$options` *(array)* — Options array (default: `[]`)
346
+ * **Returns:** *(array)* — The modified options array
347
+
348
+ #### Usage Example:
349
+ ```php
350
+ // Filter dynamic dropdown option values for MailChimp lists
351
+ add_filter('fluent_cart/integration/integration_options_mailchimp_lists', function ($options) {
352
+ // Append custom audience option definition to list
353
+ $options[] = [
354
+ 'id' => 'custom_list',
355
+ 'title' => 'Custom Audience',
356
+ ];
357
+ return $options;
358
+ });
359
+ ```
360
+
361
+ ---
362
+
363
+ ### `integration_saving_data_{$provider}`
364
+ `fluent_cart/integration/integration_saving_data_{$provider}` — Filter integration data before validation (DYNAMIC)
365
+
366
+ * **When it runs:** Dynamic filter applied to integration data before saving validation.
367
+ * **Source:** `IntegrationHelper.php` (line 62)
368
+
369
+ #### Parameters:
370
+ * `$validatedData` *(array)* — Validated integration data array
371
+ * **Returns:** *(array)* — The modified validated data array
372
+
373
+ #### Usage Example:
374
+ ```php
375
+ // Filter MailChimp integration data before saving validation
376
+ add_filter('fluent_cart/integration/integration_saving_data_mailchimp', function ($validatedData) {
377
+ // Convert tag strings to lowercase before saving
378
+ if (!empty($validatedData['tags'])) {
379
+ $validatedData['tags'] = array_map('strtolower', $validatedData['tags']);
380
+ }
381
+ return $validatedData;
382
+ });
383
+ ```
384
+
385
+ ---
386
+
387
+ ### `editing_integration_{$key}`
388
+ `fluent_cart/integration/editing_integration_{$key}` — Filter integration data when editing (DYNAMIC)
389
+
390
+ * **When it runs:** Dynamic filter applied when an integration is loaded for editing in admin UI.
391
+ * **Source:** `IntegrationHelper.php` (line 80)
392
+
393
+ #### Parameters:
394
+ * `$data` *(array)* — Integration data for editing
395
+ * `$args` *(array)* — Additional context arguments
396
+ * **Returns:** *(array)* — The modified integration data
397
+
398
+ #### Usage Example:
399
+ ```php
400
+ // Filter integration data when loading for edit in admin UI
401
+ add_filter('fluent_cart/integration/editing_integration_mailchimp', function ($data, $args) {
402
+ // Decrypt API key for editing interface display
403
+ if (!empty($data['api_key_encrypted'])) {
404
+ $data['api_key'] = decrypt($data['api_key_encrypted']);
405
+ }
406
+ return $data;
407
+ }, 10, 2);
408
+ ```
409
+
410
+ ---
411
+
412
+ ## Integration Addons
413
+
414
+ ### `addons`
415
+ `fluent_cart/integration/addons` — Filter the integration addons list
416
+
417
+ * **When it runs:** Applied when retrieving list of available integration addons in admin interface.
418
+ * **Source:** `AddonsController.php` (line 87)
419
+
420
+ #### Parameters:
421
+ * `$addons` *(array)* — Array of addon definitions
422
+ * **Returns:** *(array)* — The modified addons array
423
+
424
+ #### Usage Example:
425
+ ```php
426
+ // Filter available integration addons list in admin panel
427
+ add_filter('fluent_cart/integration/addons', function ($addons) {
428
+ // Register custom integration addon definition
429
+ $addons['my_addon'] = [
430
+ 'title' => 'My Custom Addon',
431
+ 'description' => 'Adds custom integration functionality',
432
+ 'logo' => 'https://example.com/addon-logo.png',
433
+ 'enabled' => true,
434
+ ];
435
+ return $addons;
436
+ });
437
+ ```
438
+
439
+ ---
440
+
441
+ ### `installable_repo_plugins`
442
+ `fluent_cart/installable_repo_plugins` — Filter installable plugin recommendations
443
+
444
+ * **When it runs:** Applied when retrieving recommended plugins installable from within FluentCart admin.
445
+ * **Source:** `AddonsController.php` (line 121), `GlobalIntegrationSettings.php` (line 396)
446
+
447
+ #### Parameters:
448
+ * `$plugins` *(array)* — Array of installable plugin definitions
449
+ * **Returns:** *(array)* — The modified plugins array
450
+
451
+ #### Usage Example:
452
+ ```php
453
+ // Filter recommended plugins array installable from WP admin
454
+ add_filter('fluent_cart/installable_repo_plugins', function ($plugins) {
455
+ // Append FluentCRM plugin definition to recommended plugins list
456
+ $plugins[] = [
457
+ 'title' => 'FluentCRM',
458
+ 'slug' => 'fluent-crm',
459
+ 'description' => 'Email marketing automation',
460
+ 'url' => 'https://wordpress.org/plugins/fluent-crm/',
461
+ ];
462
+ return $plugins;
463
+ });
464
+ ```
465
+
466
+ ---
467
+
468
+ ## File Storage & Downloads
469
+
470
+ ### `local_file_blocked_extensions`
471
+ `fluent_cart/local_file_blocked_extensions` — Filter blocked file extensions for local storage
472
+
473
+ * **When it runs:** Applied when validating local storage file uploads to modify blocked extension list.
474
+ * **Source:** `LocalDriver.php` (line 129)
475
+
476
+ #### Parameters:
477
+ * `$blockedExts` *(array)* — Array of blocked file extensions
478
+ * `$localFilePath` *(string)* — Local file path
479
+ * `$uploadToFilePath` *(string)* — Target upload path
480
+ * `$fileInfo` *(array)* — File information array
481
+ * **Returns:** *(array)* — The modified blocked extensions array
482
+
483
+ #### Usage Example:
484
+ ```php
485
+ // Filter blocked file extensions array for local storage driver uploads
486
+ add_filter('fluent_cart/local_file_blocked_extensions', function ($blockedExts, $localFilePath, $uploadToFilePath, $fileInfo) {
487
+ // Add SVG and WebP extensions to blocked upload list
488
+ $blockedExts[] = 'svg';
489
+ $blockedExts[] = 'webp';
490
+ return $blockedExts;
491
+ }, 10, 4);
492
+ ```
493
+
494
+ ---
495
+
496
+ ### `download_expiration_minutes`
497
+ `fluent_cart/download_expiration_minutes` — Filter S3 download link expiration time
498
+
499
+ * **When it runs:** Controls how long pre-signed S3 download URLs remain valid.
500
+ * **Source:** `S3Driver.php` (lines 237, 252)
501
+
502
+ #### Parameters:
503
+ * `$expirationMinutes` *(int)* — Expiration time in minutes
504
+ * `$context` *(array)* — Context data (`['file_path' => string, 'bucket' => string, 'driver' => 's3']`)
505
+ * **Returns:** *(int)* — The modified expiration time in minutes
506
+
507
+ #### Usage Example:
508
+ ```php
509
+ // Filter S3 pre-signed download link expiration time in minutes
510
+ add_filter('fluent_cart/download_expiration_minutes', function ($expirationMinutes, $context) {
511
+ // Extend download link validity to 120 minutes for ZIP files
512
+ if (str_ends_with($context['file_path'], '.zip')) {
513
+ return 120;
514
+ }
515
+ return $expirationMinutes;
516
+ }, 10, 2);
517
+ ```
518
+
519
+ ---
520
+
521
+ ### `download_link_validity_in_minutes`
522
+ `fluent_cart/download_link_validity_in_minutes` — Filter download link validity duration
523
+
524
+ * **When it runs:** Controls how long customer-facing download links remain valid (default: `60` minutes).
525
+ * **Source:** `Helper.php` (line 1430)
526
+
527
+ #### Parameters:
528
+ * `$minutes` *(int)* — Link validity in minutes (default: `60`)
529
+ * `$context` *(array)* — Context data (`['product_download' => Model, 'order_id' => int, 'is_admin' => bool]`)
530
+ * **Returns:** *(int)* — The modified validity in minutes
531
+
532
+ #### Usage Example:
533
+ ```php
534
+ // Filter customer-facing downloadable link validity duration in minutes
535
+ add_filter('fluent_cart/download_link_validity_in_minutes', function ($minutes, $context) {
536
+ // Grant 24-hour download link validity window for admin users
537
+ if ($context['is_admin']) {
538
+ return 1440;
539
+ }
540
+ return $minutes;
541
+ }, 10, 2);
542
+ ```
543
+
544
+ ---
545
+
546
+ ### `product_download/can_be_downloaded`
547
+ `fluent_cart/product_download/can_be_downloaded` — Filter whether a file can be downloaded
548
+
549
+ * **When it runs:** Applied during download validation to determine download permission.
550
+ * **Source:** `FileDownloader.php` (line 95)
551
+
552
+ #### Parameters:
553
+ * `$canDownload` *(bool|\WP_Error)* — Download permission boolean or rejection `WP_Error`
554
+ * **Returns:** *(bool|\WP_Error)* — The modified download permission
555
+
556
+ #### Usage Example:
557
+ ```php
558
+ // Filter whether customer is permitted to download digital file
559
+ add_filter('fluent_cart/product_download/can_be_downloaded', function ($canDownload) {
560
+ // Block file downloads during maintenance mode
561
+ if (get_option('fluent_cart_maintenance_mode')) {
562
+ return new \WP_Error('maintenance', 'Downloads are temporarily disabled during maintenance.');
563
+ }
564
+ return $canDownload;
565
+ });
566
+ ```
567
+
568
+ ---
569
+
570
+ ### `get_global_storage_settings_{$driver}`
571
+ `fluent_cart/storage/get_global_storage_settings_{$driver}` — Filter storage driver settings (DYNAMIC)
572
+
573
+ * **When it runs:** Dynamic filter applied when retrieving settings for a specific storage driver (`s3`, `local`).
574
+ * **Source:** `api/StorageDrivers.php` (line 18)
575
+
576
+ #### Parameters:
577
+ * `$settings` *(array)* — Storage driver settings array (default: `[]`)
578
+ * **Returns:** *(array)* — The modified settings array
579
+
580
+ #### Usage Example:
581
+ ```php
582
+ // Filter global S3 storage driver settings array
583
+ add_filter('fluent_cart/storage/get_global_storage_settings_s3', function ($settings) {
584
+ // Override S3 bucket and region from environment constants if set
585
+ $settings['bucket'] = defined('S3_BUCKET') ? S3_BUCKET : $settings['bucket'];
586
+ $settings['region'] = defined('S3_REGION') ? S3_REGION : $settings['region'];
587
+ return $settings;
588
+ });
589
+ ```
590
+
591
+ ---
592
+
593
+ ### `get_global_storage_drivers`
594
+ `fluent_cart/storage/get_global_storage_drivers` — Filter all available storage drivers
595
+
596
+ * **When it runs:** Applied when retrieving list of all available storage drivers.
597
+ * **Source:** `StorageDrivers.php` (line 28)
598
+
599
+ #### Parameters:
600
+ * `$drivers` *(array)* — Array of storage driver definitions (default: `[]`)
601
+ * **Returns:** *(array)* — The modified drivers array
602
+
603
+ #### Usage Example:
604
+ ```php
605
+ // Filter available file storage driver definitions array
606
+ add_filter('fluent_cart/storage/get_global_storage_drivers', function ($drivers) {
607
+ // Register custom Backblaze B2 storage driver handler
608
+ $drivers['backblaze'] = [
609
+ 'title' => 'Backblaze B2',
610
+ 'description' => 'Store files on Backblaze B2',
611
+ 'handler' => 'BackblazeDriver',
612
+ ];
613
+ return $drivers;
614
+ });
615
+ ```
616
+
617
+ ---
618
+
619
+ ### `get_global_storage_driver_status_{$driver}`
620
+ `fluent_cart/storage/get_global_storage_driver_status_{$driver}` — Filter storage driver status (DYNAMIC)
621
+
622
+ * **When it runs:** Dynamic filter retrieving connection status for a specific storage driver.
623
+ * **Source:** `StorageDrivers.php` (line 65)
624
+
625
+ #### Parameters:
626
+ * `$status` *(array)* — Driver status array (default: `[]`)
627
+ * **Returns:** *(array)* — The modified status array
628
+
629
+ #### Usage Example:
630
+ ```php
631
+ // Filter connection status array for S3 storage driver
632
+ add_filter('fluent_cart/storage/get_global_storage_driver_status_s3', function ($status) {
633
+ // Set connected status and success message for S3 driver
634
+ $status['connected'] = true;
635
+ $status['message'] = 'Connected to S3 bucket successfully';
636
+ return $status;
637
+ });
638
+ ```
639
+
640
+ ---
641
+
642
+ ### `verify_driver_connect_info_{$driver}`
643
+ `fluent_cart/verify_driver_connect_info_{$driver}` — Filter driver connection verification (DYNAMIC)
644
+
645
+ * **When it runs:** Dynamic filter applied when verifying connection info for a storage driver.
646
+ * **Source:** `StorageDrivers.php` (line 79)
647
+
648
+ #### Parameters:
649
+ * `$settings` *(array)* — Driver connection settings array
650
+ * **Returns:** *(array)* — The modified settings array
651
+
652
+ #### Usage Example:
653
+ ```php
654
+ // Filter S3 storage driver connection verification check
655
+ add_filter('fluent_cart/verify_driver_connect_info_s3', function ($settings) {
656
+ // Verify AWS S3 credentials via SDK bucket listing test
657
+ try {
658
+ $client = new \Aws\S3\S3Client($settings);
659
+ $client->listBuckets();
660
+ $settings['verified'] = true;
661
+ } catch (\Exception $e) {
662
+ $settings['error'] = $e->getMessage();
663
+ }
664
+ return $settings;
665
+ });
666
+ ```
667
+
668
+ ---
669
+
670
+ ### `storage_settings_before_update_{$slug}`
671
+ `fluent_cart/storage/storage_settings_before_update_{$slug}` — Filter storage settings before saving (DYNAMIC)
672
+
673
+ * **When it runs:** Dynamic filter applied just before storage driver settings are saved.
674
+ * **Source:** `BaseStorageDriver.php` (line 152)
675
+
676
+ #### Parameters:
677
+ * `$settings` *(array)* — New settings array
678
+ * `$oldSettings` *(array)* — Previous settings array
679
+ * **Returns:** *(array)* — The modified settings array
680
+
681
+ #### Usage Example:
682
+ ```php
683
+ // Filter S3 storage driver settings before saving to database
684
+ add_filter('fluent_cart/storage/storage_settings_before_update_s3', function ($settings, $oldSettings) {
685
+ // Preserve existing S3 secret key if omitted in update request
686
+ if (empty($settings['secret_key']) && !empty($oldSettings['secret_key'])) {
687
+ $settings['secret_key'] = $oldSettings['secret_key'];
688
+ }
689
+ return $settings;
690
+ }, 10, 2);
691
+ ```
692
+
693
+ ---
694
+
695
+ ## Localization & Address
696
+
697
+ ### `country_state_options`
698
+ `fluent_cart/country_state_options` — Filter country and state options
699
+
700
+ * **When it runs:** Applied when retrieving country and state dropdown options for address forms.
701
+ * **Source:** `LocalizationManager.php` (line 425)
702
+
703
+ #### Parameters:
704
+ * `$options` *(array)* — Country/state options array
705
+ * **Returns:** *(array)* — The modified options array
706
+
707
+ #### Usage Example:
708
+ ```php
709
+ // Filter country and state dropdown options array for address forms
710
+ add_filter('fluent_cart/country_state_options', function ($options) {
711
+ // Exclude invalid country code XX from countries dropdown list
712
+ unset($options['countries']['XX']);
713
+ return $options;
714
+ });
715
+ ```
716
+
717
+ ---
718
+
719
+ ### `address/postcode/format`
720
+ `fluent_cart/address/postcode/format` — Filter postcode formatting
721
+
722
+ * **When it runs:** Applied when formatting a postcode value, typically during address validation.
723
+ * **Source:** `PostcodeVerification.php` (line 53)
724
+
725
+ #### Parameters:
726
+ * `$postcode` *(string)* — Trimmed postcode value
727
+ * `$country` *(string)* — Country code (ISO 3166-1 alpha-2)
728
+ * **Returns:** *(string)* — The formatted postcode string
729
+
730
+ #### Usage Example:
731
+ ```php
732
+ // Filter formatted postcode string value during verification
733
+ add_filter('fluent_cart/address/postcode/format', function ($postcode, $country) {
734
+ // Format UK postcode with space delimiter
735
+ if ($country === 'GB' && strlen($postcode) > 3 && strpos($postcode, ' ') === false) {
736
+ return substr($postcode, 0, -3) . ' ' . substr($postcode, -3);
737
+ }
738
+ return $postcode;
739
+ }, 10, 2);
740
+ ```
741
+
742
+ ---
743
+
744
+ ### `address/postcode/is_valid`
745
+ `fluent_cart/address/postcode/is_valid` — Filter postcode validation result
746
+
747
+ * **When it runs:** Applied after postcode validation to enforce custom validation rules.
748
+ * **Source:** `PostcodeVerification.php` (line 154)
749
+
750
+ #### Parameters:
751
+ * `$valid` *(bool)* — Whether postcode is valid
752
+ * `$postcode` *(string)* — Postcode being validated
753
+ * `$country` *(string)* — Country code (ISO 3166-1 alpha-2)
754
+ * **Returns:** *(bool)* — The modified validation result
755
+
756
+ #### Usage Example:
757
+ ```php
758
+ // Filter postcode validity verification result boolean
759
+ add_filter('fluent_cart/address/postcode/is_valid', function ($valid, $postcode, $country) {
760
+ // Validate 5-digit numeric postcode regex for custom country XX
761
+ if ($country === 'XX') {
762
+ return preg_match('/^\d{5}$/', $postcode) === 1;
763
+ }
764
+ return $valid;
765
+ }, 10, 3);
766
+ ```
767
+
768
+ ---
769
+
770
+ ### `util/countries` (legacy)
771
+ `fluent-cart/util/countries` — Filter the country list
772
+
773
+ * **When it runs:** Applied when retrieving full list of countries. Note hyphenated prefix (`fluent-cart/`).
774
+ * **Source:** `Helper.php` (line 1140)
775
+
776
+ #### Parameters:
777
+ * `$options` *(array)* — Array of country code => country name pairs
778
+ * **Returns:** *(array)* — The modified country list array
779
+
780
+ #### Usage Example:
781
+ ```php
782
+ // Filter global country list array (legacy hyphenated hook name)
783
+ add_filter('fluent-cart/util/countries', function ($options) {
784
+ // Restrict countries list to US, CA, GB, and AU
785
+ return array_intersect_key($options, array_flip(['US', 'CA', 'GB', 'AU']));
786
+ });
787
+ ```
788
+
789
+ ---
790
+
791
+ ## Templates & Frontend
792
+
793
+ ### `template/disable_taxonomy_fallback`
794
+ `fluent_cart/template/disable_taxonomy_fallback` — Disable taxonomy fallback template
795
+
796
+ * **When it runs:** Controls whether taxonomy fallback template should be disabled (default: `false`).
797
+ * **Source:** `TemplateLoader.php` (line 113)
798
+
799
+ #### Parameters:
800
+ * `$disable` *(bool)* — Whether to disable taxonomy fallback
801
+ * **Returns:** *(bool)* — The modified boolean value
802
+
803
+ #### Usage Example:
804
+ ```php
805
+ // Filter whether to disable taxonomy fallback template rendering
806
+ add_filter('fluent_cart/template/disable_taxonomy_fallback', function ($disable) {
807
+ // Disable taxonomy template fallback when custom theme template is active
808
+ return true;
809
+ });
810
+ ```
811
+
812
+ ---
813
+
814
+ ### `has_block_template`
815
+ `fluent_cart/has_block_template` — Filter block template existence check
816
+
817
+ * **When it runs:** Applied when checking if block template exists for current page.
818
+ * **Source:** `TemplateLoader.php` (line 193)
819
+
820
+ #### Parameters:
821
+ * `$hasTemplate` *(bool)* — Whether a block template exists
822
+ * **Returns:** *(bool)* — The modified boolean result
823
+
824
+ #### Usage Example:
825
+ ```php
826
+ // Filter block template existence check result for current page
827
+ add_filter('fluent_cart/has_block_template', function ($hasTemplate) {
828
+ // Force classic template rendering by returning false
829
+ return false;
830
+ });
831
+ ```
832
+
833
+ ---
834
+
835
+ ### `template_loader_files`
836
+ `fluent_cart/template_loader_files` — Filter template files to load
837
+
838
+ * **When it runs:** Applied when determining which template files should be loaded for current request.
839
+ * **Source:** `TemplateLoader.php` (line 206)
840
+
841
+ #### Parameters:
842
+ * `$files` *(array)* — Array of template file paths (default: `[]`)
843
+ * **Returns:** *(array)* — The modified template files array
844
+
845
+ #### Usage Example:
846
+ ```php
847
+ // Filter array of template file paths loaded for request
848
+ add_filter('fluent_cart/template_loader_files', function ($files) {
849
+ // Append custom stylesheet theme template file path
850
+ $files[] = get_stylesheet_directory() . '/fluent-cart/custom-template.php';
851
+ return $files;
852
+ });
853
+ ```
854
+
855
+ ---
856
+
857
+ ### `template_path`
858
+ `fluent_cart/template_path` — Filter theme template path
859
+
860
+ * **When it runs:** Controls directory path within a theme where FluentCart template overrides are located (default: `'fluent-cart/'`).
861
+ * **Source:** `TemplateLoader.php` (line 248)
862
+
863
+ #### Parameters:
864
+ * `$path` *(string)* — Template directory path
865
+ * **Returns:** *(string)* — The modified template path
866
+
867
+ #### Usage Example:
868
+ ```php
869
+ // Filter theme directory path storing FluentCart template overrides
870
+ add_filter('fluent_cart/template_path', function ($path) {
871
+ // Override template overrides directory path in active theme
872
+ return 'my-store/templates/';
873
+ });
874
+ ```
875
+
876
+ ---
877
+
878
+ ### `fluent_cart_template_part_content`
879
+ `fluent_cart_template_part_content` — Filter template part content
880
+
881
+ * **When it runs:** Applied to template part content before rendering.
882
+ * **Source:** `ProductModalTemplatePart.php` (line 245)
883
+
884
+ #### Parameters:
885
+ * `$content` *(string)* — Template part content string
886
+ * `$slug` *(string)* — Template part slug
887
+ * `$args` *(array)* — Template arguments
888
+ * **Returns:** *(string)* — The modified content string
889
+
890
+ #### Usage Example:
891
+ ```php
892
+ // Filter template part content string before rendering
893
+ add_filter('fluent_cart_template_part_content', function ($content, $slug, $args) {
894
+ // Wrap product card template part HTML in custom container div
895
+ if ($slug === 'product-card') {
896
+ $content = '<div class="custom-wrapper">' . $content . '</div>';
897
+ }
898
+ return $content;
899
+ }, 10, 3);
900
+ ```
901
+
902
+ ---
903
+
904
+ ### `fluent_cart_template_part_content_{$slug}`
905
+ `fluent_cart_template_part_content_{$slug}` — Filter template part content by slug (DYNAMIC)
906
+
907
+ * **When it runs:** Dynamic filter applied to a specific template part's content.
908
+ * **Source:** `ProductModalTemplatePart.php` (line 246)
909
+
910
+ #### Parameters:
911
+ * `$content` *(string)* — Template part content string
912
+ * `$args` *(array)* — Template arguments
913
+ * **Returns:** *(string)* — The modified content string
914
+
915
+ #### Usage Example:
916
+ ```php
917
+ // Filter product card template part content by slug
918
+ add_filter('fluent_cart_template_part_content_product-card', function ($content, $args) {
919
+ // Append New badge HTML element to product card content
920
+ $content .= '<span class="badge">New</span>';
921
+ return $content;
922
+ }, 10, 2);
923
+ ```
924
+
925
+ ---
926
+
927
+ ### `fluent_cart_template_part_output`
928
+ `fluent_cart_template_part_output` — Filter template part output
929
+
930
+ * **When it runs:** Applied to final rendered output of a template part.
931
+ * **Source:** `ProductModalTemplatePart.php` (line 252)
932
+
933
+ #### Parameters:
934
+ * `$output` *(string)* — Rendered template part output HTML
935
+ * **Returns:** *(string)* — The modified output string
936
+
937
+ #### Usage Example:
938
+ ```php
939
+ // Filter final rendered output string of template part
940
+ add_filter('fluent_cart_template_part_output', function ($output) {
941
+ // Minify rendered template part output whitespace
942
+ return preg_replace('/\s+/', ' ', $output);
943
+ });
944
+ ```
945
+
946
+ ---
947
+
948
+ ### `fluent_cart_template_part_output_{$slug}`
949
+ `fluent_cart_template_part_output_{$slug}` — Filter template part output by slug (DYNAMIC)
950
+
951
+ * **When it runs:** Dynamic filter applied to final rendered output of a specific template part.
952
+ * **Source:** `ProductModalTemplatePart.php` (line 253)
953
+
954
+ #### Parameters:
955
+ * `$output` *(string)* — Rendered output HTML
956
+ * **Returns:** *(string)* — The modified output string
957
+
958
+ #### Usage Example:
959
+ ```php
960
+ // Filter final output string of product modal template part
961
+ add_filter('fluent_cart_template_part_output_product-modal', function ($output) {
962
+ // Inject custom tracking data attribute into modal container div
963
+ return str_replace('<div class="fct-modal"', '<div class="fct-modal" data-tracking="true"', $output);
964
+ });
965
+ ```
966
+
967
+ ---
968
+
969
+ ### `buttons/enable_floating_cart_button`
970
+ `fluent_cart/buttons/enable_floating_cart_button` — Filter floating cart button visibility
971
+
972
+ * **When it runs:** Controls whether floating cart button is displayed on frontend (default: `true`).
973
+ * **Source:** `app/Hooks/Cart/CartLoader.php` (line 41)
974
+
975
+ #### Parameters:
976
+ * `$enabled` *(bool)* — Whether floating cart button is enabled
977
+ * **Returns:** *(bool)* — The modified boolean value
978
+
979
+ #### Usage Example:
980
+ ```php
981
+ // Filter frontend floating cart button visibility toggle
982
+ add_filter('fluent_cart/buttons/enable_floating_cart_button', function ($enabled) {
983
+ // Disable floating cart button on landing page
984
+ if (is_page('landing-page')) {
985
+ return false;
986
+ }
987
+ return $enabled;
988
+ });
989
+ ```
990
+
991
+ ---
992
+
993
+ ## Widgets & Dashboard
994
+
995
+ ### `{$widgetName}`
996
+ `fluent_cart/{$widgetName}` — Filter widget data by name (DYNAMIC)
997
+
998
+ * **When it runs:** Dynamic filter applied when dashboard widget retrieves its data.
999
+ * **Source:** `app/Services/Widgets/BaseWidget.php` (line 16)
1000
+
1001
+ #### Parameters:
1002
+ * `$widgetData` *(mixed)* — Widget data array returned by `widgetData()`
1003
+ * **Returns:** *(mixed)* — The modified widget data
1004
+
1005
+ #### Usage Example:
1006
+ ```php
1007
+ // Filter dashboard revenue widget data array dynamically
1008
+ add_filter('fluent_cart/revenue_widget', function ($widgetData) {
1009
+ // Inject calculated custom metric value into revenue widget data
1010
+ $widgetData['custom_metric'] = calculate_custom_metric();
1011
+ return $widgetData;
1012
+ });
1013
+ ```
1014
+
1015
+ ---
1016
+
1017
+ ### `widgets/{$filter}`
1018
+ `fluent_cart/widgets/{$filter}` — Filter widget data by filter key (DYNAMIC)
1019
+
1020
+ * **When it runs:** Dynamic filter applied when retrieving widget data for filter key in widgets controller.
1021
+ * **Source:** `WidgetsController.php` (line 36)
1022
+
1023
+ #### Parameters:
1024
+ * `$result` *(array)* — Widget result data array (default: `[]`)
1025
+ * `$data` *(array)* — Request data array
1026
+ * **Returns:** *(array)* — The modified widget data array
1027
+
1028
+ #### Usage Example:
1029
+ ```php
1030
+ // Filter sales overview widget chart data array dynamically
1031
+ add_filter('fluent_cart/widgets/sales_overview', function ($result, $data) {
1032
+ // Attach custom chart dataset structure to sales overview widget
1033
+ $result['custom_chart'] = [
1034
+ 'labels' => ['Jan', 'Feb', 'Mar'],
1035
+ 'data' => [100, 200, 150],
1036
+ ];
1037
+ return $result;
1038
+ }, 10, 2);
1039
+ ```
1040
+
1041
+ ---
1042
+
1043
+ ### `promo_gateways`
1044
+ `fluent_cart/promo_gateways` — Filter promotional gateways
1045
+
1046
+ * **When it runs:** Applied when retrieving list of promotional payment gateways shown in admin.
1047
+ * **Source:** `PromoGatewaysHandler.php` (line 36)
1048
+
1049
+ #### Parameters:
1050
+ * `$defaultGateways` *(array)* — Array of default promotional gateways
1051
+ * **Returns:** *(array)* — The modified gateways array
1052
+
1053
+ #### Usage Example:
1054
+ ```php
1055
+ // Filter promotional payment gateways list in admin panel
1056
+ add_filter('fluent_cart/promo_gateways', function ($gateways) {
1057
+ // Remove specific example gateway from promotional gateways
1058
+ unset($gateways['example_gateway']);
1059
+ return $gateways;
1060
+ });
1061
+ ```
1062
+
1063
+ ---
1064
+
1065
+ ### `addon_gateways`
1066
+ `fluent_cart/addon_gateways` — Filter addon payment gateways
1067
+
1068
+ * **When it runs:** Applied when retrieving list of addon payment gateways.
1069
+ * **Source:** `AddonGatewaysHandler.php` (line 36)
1070
+
1071
+ #### Parameters:
1072
+ * `$defaultGateways` *(array)* — Array of default addon gateways
1073
+ * **Returns:** *(array)* — The modified gateways array
1074
+
1075
+ #### Usage Example:
1076
+ ```php
1077
+ // Filter addon payment gateways list array
1078
+ add_filter('fluent_cart/addon_gateways', function ($gateways) {
1079
+ // Register custom payment gateway addon definition
1080
+ $gateways['custom_pay'] = [
1081
+ 'title' => 'Custom Pay',
1082
+ 'description' => 'Custom payment gateway addon',
1083
+ 'is_active' => true,
1084
+ ];
1085
+ return $gateways;
1086
+ });
1087
+ ```
1088
+
1089
+ ---
1090
+
1091
+ ## Advanced List Filters
1092
+
1093
+ ### `{$filter}_list_filter_query`
1094
+ `fluent_cart/{$filter}_list_filter_query` — Filter list filter query (DYNAMIC)
1095
+
1096
+ * **When it runs:** Dynamic filter applied when building database queries for filtered list pages (orders, customers, subscriptions, etc.).
1097
+ * **Source:** `BaseFilter.php` (lines 962, 971)
1098
+
1099
+ #### Parameters:
1100
+ * `$query` *(\FluentCart\Framework\Database\Orm\Builder)* — Eloquent query builder instance
1101
+ * **Returns:** *(\FluentCart\Framework\Database\Orm\Builder)* — The modified query builder
1102
+
1103
+ #### Usage Example:
1104
+ ```php
1105
+ // Filter Eloquent query builder for admin orders list view
1106
+ add_filter('fluent_cart/orders_list_filter_query', function ($query) {
1107
+ // Restrict orders list query to orders created within last 30 days
1108
+ $query->where('created_at', '>=', gmdate('Y-m-d H:i:s', strtotime('-30 days')));
1109
+ return $query;
1110
+ });
1111
+ ```
1112
+
1113
+ ---
1114
+
1115
+ ### `{$filterName}_filter_options`
1116
+ `fluent_cart/{$filterName}_filter_options` — Filter options for list page filters (DYNAMIC)
1117
+
1118
+ * **When it runs:** Dynamic filter applied when retrieving available filter options for admin list pages.
1119
+ * **Source:** `BaseFilter.php` (line 995)
1120
+
1121
+ #### Parameters:
1122
+ * `$options` *(array)* — Filter options array
1123
+ * **Returns:** *(array)* — The modified filter options array
1124
+
1125
+ #### Usage Example:
1126
+ ```php
1127
+ // Filter available filter dropdown options for orders list page
1128
+ add_filter('fluent_cart/orders_filter_options', function ($options) {
1129
+ // Inject custom status dropdown filter option for orders list page
1130
+ $options['custom_status'] = [
1131
+ 'label' => 'Custom Status',
1132
+ 'type' => 'select',
1133
+ 'options' => ['pending_review' => 'Pending Review'],
1134
+ ];
1135
+ return $options;
1136
+ });
1137
+ ```
1138
+
1139
+ ---
1140
+
1141
+ ### `{$filterName}_table_columns`
1142
+ `fluent_cart/{$filterName}_table_columns` — Filter table columns for list pages (DYNAMIC)
1143
+
1144
+ * **When it runs:** Dynamic filter applied when retrieving table column definitions for admin list pages.
1145
+ * **Source:** `BaseFilter.php` (line 1038)
1146
+
1147
+ #### Parameters:
1148
+ * `$columns` *(array)* — Table column definitions array (default: `[]`)
1149
+ * **Returns:** *(array)* — The modified columns array
1150
+
1151
+ #### Usage Example:
1152
+ ```php
1153
+ // Filter table column definitions for admin orders list view
1154
+ add_filter('fluent_cart/orders_table_columns', function ($columns) {
1155
+ // Append custom field column definition to orders table
1156
+ $columns['custom_field'] = [
1157
+ 'label' => 'Custom Field',
1158
+ 'sortable' => true,
1159
+ 'width' => '120px',
1160
+ ];
1161
+ return $columns;
1162
+ });
1163
+ ```
1164
+
1165
+ ---
1166
+
1167
+ ### `advanced_filter_options_{$dataKey}`
1168
+ `fluent_cart/advanced_filter_options_{$dataKey}` — Filter advanced filter options (DYNAMIC)
1169
+
1170
+ * **When it runs:** Dynamic filter applied when retrieving options for advanced filter UI.
1171
+ * **Source:** `AdvanceFilterController.php` (line 46)
1172
+
1173
+ #### Parameters:
1174
+ * `$options` *(array)* — Filter options array
1175
+ * **Returns:** *(array)* — The modified options array
1176
+
1177
+ #### Usage Example:
1178
+ ```php
1179
+ // Filter options array for advanced filter UI payment methods
1180
+ add_filter('fluent_cart/advanced_filter_options_payment_methods', function ($options) {
1181
+ // Append custom gateway option to advanced filter UI
1182
+ $options[] = [
1183
+ 'value' => 'custom_gateway',
1184
+ 'label' => 'Custom Gateway',
1185
+ ];
1186
+ return $options;
1187
+ });
1188
+ ```
1189
+
1190
+ ---
1191
+
1192
+ ## Plugin Installer
1193
+
1194
+ ### `outside_addon/handle_cdn_install`
1195
+ `fluent_cart/outside_addon/handle_cdn_install` — Filter CDN addon installation
1196
+
1197
+ * **When it runs:** Applied when attempting to install an addon from a CDN source. Return non-null value to handle installation manually.
1198
+ * **Source:** `BackgroundInstaller.php` (line 143)
1199
+
1200
+ #### Parameters:
1201
+ * `$result` *(mixed)* — Installation result (default: `null`)
1202
+ * **Returns:** *(mixed)* — The installation result, or `null` for default handling
1203
+
1204
+ #### Usage Example:
1205
+ ```php
1206
+ // Intercept addon installation from CDN external source
1207
+ add_filter('fluent_cart/outside_addon/handle_cdn_install', function ($result) {
1208
+ // Handle custom CDN addon installation logic
1209
+ if ($result === null) {
1210
+ return ['success' => true, 'message' => 'Installed from custom CDN'];
1211
+ }
1212
+ return $result;
1213
+ });
1214
+ ```
1215
+
1216
+ ---
1217
+
1218
+ ### `outside_addon/handle_install`
1219
+ `fluent_cart/outside_addon/handle_install` — Filter external addon installation
1220
+
1221
+ * **When it runs:** Applied when installing an addon from an external source. Return non-null value to handle installation manually.
1222
+ * **Source:** `BackgroundInstaller.php` (line 164)
1223
+
1224
+ #### Parameters:
1225
+ * `$result` *(mixed)* — Installation result (default: `null`)
1226
+ * **Returns:** *(mixed)* — The installation result, or `null` for default handling
1227
+
1228
+ #### Usage Example:
1229
+ ```php
1230
+ // Intercept external addon installation process
1231
+ add_filter('fluent_cart/outside_addon/handle_install', function ($result) {
1232
+ // Return success response payload for custom external addon installer
1233
+ return ['success' => true, 'message' => 'Addon installed successfully'];
1234
+ });
1235
+ ```
1236
+
1237
+ ---
1238
+
1239
+ ## Pro: E-Invoicing
1240
+
1241
+ ### `einvoice/buyer_vat_id` (Pro)
1242
+ `fluent_cart/einvoice/buyer_vat_id` — Filter buyer VAT ID written to e-invoice
1243
+
1244
+ * **When it runs:** Applied in `En16931InvoiceMapper` while mapping order to EN 16931 e-invoice (BT-48) XML. Requires Pro plugin.
1245
+ * **Source:** `fluent-cart-pro/.../En16931InvoiceMapper.php` (line 154)
1246
+
1247
+ #### Parameters:
1248
+ * `$buyerVatId` *(string)* — Resolved buyer VAT identifier
1249
+ * `$context` *(array)* — Context data (`['order' => Order]`)
1250
+ * **Returns:** *(string)* — The buyer VAT identifier string to write
1251
+
1252
+ #### Usage Example:
1253
+ ```php
1254
+ // Filter buyer VAT identification string written to EN 16931 e-invoice (Pro)
1255
+ add_filter('fluent_cart/einvoice/buyer_vat_id', function ($buyerVatId, $context) {
1256
+ // Prepend billing country code prefix to buyer VAT ID if omitted
1257
+ $country = $context['order']->billing_address->country ?? '';
1258
+ if ($country && strpos($buyerVatId, $country) !== 0) {
1259
+ $buyerVatId = $country . $buyerVatId;
1260
+ }
1261
+
1262
+ return $buyerVatId;
1263
+ }, 10, 2);
1264
+ ```
1265
+
1266
+ ---
1267
+
1268
+ ### `einvoice/tax_category` (Pro)
1269
+ `fluent_cart/einvoice/tax_category` — Filter EN 16931 VAT category for e-invoice line
1270
+
1271
+ * **When it runs:** Applied in `En16931InvoiceMapper` after resolving EN 16931 VAT category for invoice line or shipping charge. Requires Pro plugin.
1272
+ * **Source:** `fluent-cart-pro/.../En16931InvoiceMapper.php` (line 357)
1273
+
1274
+ #### Parameters:
1275
+ * `$resolved` *(array)* — Category data (`categoryCode`, `ratePercent`, `exemptionReasonCode`, `exemptionReasonText`)
1276
+ * `$context` *(array)* — Context data (`['order' => Order, 'line' => LineItem|null]`)
1277
+ * **Returns:** *(array)* — The modified VAT category data array
1278
+
1279
+ #### Usage Example:
1280
+ ```php
1281
+ // Filter EN 16931 VAT tax category data for e-invoice line item (Pro)
1282
+ add_filter('fluent_cart/einvoice/tax_category', function ($resolved, $context) {
1283
+ // Force exempt category E for target product line post ID 123
1284
+ if ($context['line'] && ($context['line']->post_id ?? 0) === 123) {
1285
+ $resolved['categoryCode'] = 'E';
1286
+ $resolved['ratePercent'] = 0.0;
1287
+ $resolved['exemptionReasonCode'] = 'VATEX-EU-O';
1288
+ $resolved['exemptionReasonText'] = 'Exempt supply';
1289
+ }
1290
+
1291
+ return $resolved;
1292
+ }, 10, 2);
1293
+ ```
1294
+
1295
+ ---
1296
+
1297
+ ## Pro: Licensing API
1298
+
1299
+ ### `license/checking_error` (Pro)
1300
+ `fluent_cart/license/checking_error` — Filter license check error response
1301
+
1302
+ * **When it runs:** Applied when license check encounters an error to customize error response payload. Requires Pro plugin.
1303
+ * **Source:** `LicenseApiHandler.php` (lines 45, 56)
1304
+
1305
+ #### Parameters:
1306
+ * `$error` *(array)* — Error response array
1307
+ * **Returns:** *(array)* — Modified error response array
1308
+
1309
+ #### Usage Example:
1310
+ ```php
1311
+ // Filter license verification error response array (Pro)
1312
+ add_filter('fluent_cart/license/checking_error', function ($error) {
1313
+ // Override license check error message string
1314
+ $error['message'] = 'Please contact support for license verification.';
1315
+ return $error;
1316
+ });
1317
+ ```
1318
+
1319
+ ---
1320
+
1321
+ ### `license/check_item_id` (Pro)
1322
+ `fluent_cart/license/check_item_id` — Filter item ID validation during license check
1323
+
1324
+ * **When it runs:** Controls whether item ID should be validated during license check API request (default: `true`). Requires Pro plugin.
1325
+ * **Source:** `LicenseApiHandler.php` (line 54)
1326
+
1327
+ #### Parameters:
1328
+ * `$checkItemId` *(bool)* — Whether to check item ID
1329
+ * **Returns:** *(bool)* — Modified boolean value
1330
+
1331
+ #### Usage Example:
1332
+ ```php
1333
+ // Filter whether item ID is validated during license check API call (Pro)
1334
+ add_filter('fluent_cart/license/check_item_id', function ($checkItemId) {
1335
+ // Skip item ID check during license check API request
1336
+ return false;
1337
+ });
1338
+ ```
1339
+
1340
+ ---
1341
+
1342
+ ### `license/check_license_response` (Pro)
1343
+ `fluent_cart/license/check_license_response` — Filter license check API response
1344
+
1345
+ * **When it runs:** Applied to license check API response before returning to client. Requires Pro plugin.
1346
+ * **Source:** `LicenseApiHandler.php` (line 83)
1347
+
1348
+ #### Parameters:
1349
+ * `$returnData` *(array)* — License check response data array
1350
+ * **Returns:** *(array)* — Modified response data array
1351
+
1352
+ #### Usage Example:
1353
+ ```php
1354
+ // Filter license check API response payload before returning to client (Pro)
1355
+ add_filter('fluent_cart/license/check_license_response', function ($returnData) {
1356
+ // Append custom support URL string to license check API response
1357
+ $returnData['support_url'] = 'https://example.com/support';
1358
+ return $returnData;
1359
+ });
1360
+ ```
1361
+
1362
+ ---
1363
+
1364
+ ### `license/activate_license_response` (Pro)
1365
+ `fluent_cart/license/activate_license_response` — Filter license activation API response
1366
+
1367
+ * **When it runs:** Applied to license activation API response before returning to client. Requires Pro plugin.
1368
+ * **Source:** `LicenseApiHandler.php` (lines 170, 274)
1369
+
1370
+ #### Parameters:
1371
+ * `$returnData` *(array)* — Activation response data array
1372
+ * **Returns:** *(array)* — Modified response data array
1373
+
1374
+ #### Usage Example:
1375
+ ```php
1376
+ // Filter license activation API response payload (Pro)
1377
+ add_filter('fluent_cart/license/activate_license_response', function ($returnData) {
1378
+ // Append activated_at timestamp string to license activation response
1379
+ $returnData['activated_at'] = gmdate('Y-m-d H:i:s');
1380
+ return $returnData;
1381
+ });
1382
+ ```
1383
+
1384
+ ---
1385
+
1386
+ ### `license/deactivate_license_response` (Pro)
1387
+ `fluent_cart/license/deactivate_license_response` — Filter license deactivation API response
1388
+
1389
+ * **When it runs:** Applied to license deactivation API response before returning to client. Requires Pro plugin.
1390
+ * **Source:** `LicenseApiHandler.php` (line 356)
1391
+
1392
+ #### Parameters:
1393
+ * `$returnData` *(array)* — Deactivation response data array
1394
+ * **Returns:** *(array)* — Modified response data array
1395
+
1396
+ #### Usage Example:
1397
+ ```php
1398
+ // Filter license deactivation API response payload (Pro)
1399
+ add_filter('fluent_cart/license/deactivate_license_response', function ($returnData) {
1400
+ // Append deactivation notice text string to response
1401
+ $returnData['notice'] = 'License deactivated. You can reactivate on another site.';
1402
+ return $returnData;
1403
+ });
1404
+ ```
1405
+
1406
+ ---
1407
+
1408
+ ### `license/get_version_response` (Pro)
1409
+ `fluent_cart/license/get_version_response` — Filter version check API response
1410
+
1411
+ * **When it runs:** Applied to version check API response to modify changelog or update information. Requires Pro plugin.
1412
+ * **Source:** `LicenseApiHandler.php` (line 463)
1413
+
1414
+ #### Parameters:
1415
+ * `$changeLogData` *(array)* — Version and changelog response data array
1416
+ * **Returns:** *(array)* — Modified response data array
1417
+
1418
+ #### Usage Example:
1419
+ ```php
1420
+ // Filter software update version check API response payload (Pro)
1421
+ add_filter('fluent_cart/license/get_version_response', function ($changeLogData) {
1422
+ // Append custom patch entry string to changelog section
1423
+ $changeLogData['sections']['changelog'] .= "\n* Custom patch applied";
1424
+ return $changeLogData;
1425
+ });
1426
+ ```
1427
+
1428
+ ---
1429
+
1430
+ ### `license/santized_url` (Pro)
1431
+ `fluent_cart/license/santized_url` — Filter sanitized URL for license validation
1432
+
1433
+ * **When it runs:** Applied when sanitizing site URL during license activation or validation. Requires Pro plugin.
1434
+ * **Source:** `LicenseHelper.php` (line 36)
1435
+
1436
+ #### Parameters:
1437
+ * `$url` *(string)* — Sanitized URL string
1438
+ * `$originalUrl` *(string)* — Original URL before sanitization
1439
+ * **Returns:** *(string)* — Modified sanitized URL string
1440
+
1441
+ #### Usage Example:
1442
+ ```php
1443
+ // Filter sanitized URL string used during license validation (Pro)
1444
+ add_filter('fluent_cart/license/santized_url', function ($url, $originalUrl) {
1445
+ // Strip www subdomain prefix from sanitized site URL
1446
+ return str_replace('://www.', '://', $url);
1447
+ }, 10, 2);
1448
+ ```
1449
+
1450
+ ---
1451
+
1452
+ ## Pro: License Validation & Staging
1453
+
1454
+ ### `fluent_cart_sl/is_local_site` (Pro)
1455
+ `fluent_cart_sl/is_local_site` — Filter local/staging site detection
1456
+
1457
+ * **When it runs:** Applied when determining if current site is local or staging for licensing purposes. Requires Pro plugin.
1458
+ * **Source:** `fluent-cart-pro/.../LicenseSite.php` (line 69)
1459
+
1460
+ #### Parameters:
1461
+ * `$isLocal` *(bool)* — Whether site is detected as local
1462
+ * `$context` *(array)* — Context data (`['url' => string, 'site' => string]`)
1463
+ * **Returns:** *(bool)* — Modified detection result boolean
1464
+
1465
+ #### Usage Example:
1466
+ ```php
1467
+ // Filter local or staging site detection boolean for licensing (Pro)
1468
+ add_filter('fluent_cart_sl/is_local_site', function ($isLocal, $context) {
1469
+ // Mark URLs containing .staging. as local staging sites
1470
+ if (str_contains($context['url'], '.staging.')) {
1471
+ return true;
1472
+ }
1473
+ return $isLocal;
1474
+ }, 10, 2);
1475
+ ```
1476
+
1477
+ ---
1478
+
1479
+ ### `license/staging_subdomain_patterns` (Pro)
1480
+ `fluent_cart/license/staging_subdomain_patterns` — Filter staging subdomain patterns
1481
+
1482
+ * **When it runs:** Applied when checking if URL matches known staging subdomain patterns. Requires Pro plugin.
1483
+ * **Source:** `LicenseHelper.php` (line 619)
1484
+
1485
+ #### Parameters:
1486
+ * `$patterns` *(array)* — Array of subdomain patterns indicating staging sites
1487
+ * **Returns:** *(array)* — Modified patterns array
1488
+
1489
+ #### Usage Example:
1490
+ ```php
1491
+ // Filter staging subdomain regex patterns array for licensing (Pro)
1492
+ add_filter('fluent_cart/license/staging_subdomain_patterns', function ($patterns) {
1493
+ // Append dev- and test- subdomain prefixes to staging patterns list
1494
+ $patterns[] = 'dev-';
1495
+ $patterns[] = 'test-';
1496
+ return $patterns;
1497
+ });
1498
+ ```
1499
+
1500
+ ---
1501
+
1502
+ ### `license/staging_subfolder_patterns` (Pro)
1503
+ `fluent_cart/license/staging_subfolder_patterns` — Filter staging subfolder patterns
1504
+
1505
+ * **When it runs:** Applied when checking if URL matches known staging subfolder patterns. Requires Pro plugin.
1506
+ * **Source:** `LicenseHelper.php` (line 620)
1507
+
1508
+ #### Parameters:
1509
+ * `$patterns` *(array)* — Array of subfolder patterns indicating staging sites
1510
+ * **Returns:** *(array)* — Modified patterns array
1511
+
1512
+ #### Usage Example:
1513
+ ```php
1514
+ // Filter staging subfolder path patterns array for licensing (Pro)
1515
+ add_filter('fluent_cart/license/staging_subfolder_patterns', function ($patterns) {
1516
+ // Append /staging/ and /test-site/ subfolders to staging patterns
1517
+ $patterns[] = '/staging/';
1518
+ $patterns[] = '/test-site/';
1519
+ return $patterns;
1520
+ });
1521
+ ```
1522
+
1523
+ ---
1524
+
1525
+ ### `license/staging_domains` (Pro)
1526
+ `fluent_cart/license/staging_domains` — Filter hosting provider staging domains
1527
+
1528
+ * **When it runs:** Applied when checking if URL belongs to known hosting provider staging domain. Requires Pro plugin.
1529
+ * **Source:** `LicenseHelper.php` (line 621)
1530
+
1531
+ #### Parameters:
1532
+ * `$domains` *(array)* — Array of hosting provider staging domain patterns
1533
+ * **Returns:** *(array)* — Modified domains array
1534
+
1535
+ #### Usage Example:
1536
+ ```php
1537
+ // Filter hosting provider staging domain patterns array (Pro)
1538
+ add_filter('fluent_cart/license/staging_domains', function ($domains) {
1539
+ // Append custom hosting provider staging domain patterns
1540
+ $domains[] = 'mystaginghost.com';
1541
+ $domains[] = 'preview.myhost.io';
1542
+ return $domains;
1543
+ });
1544
+ ```
1545
+
1546
+ ---
1547
+
1548
+ ### `license/is_staging_site_result` (Pro)
1549
+ `fluent_cart/license/is_staging_site_result` — Filter final staging site detection result
1550
+
1551
+ * **When it runs:** Applied after all staging detection checks to provide final boolean result (default: `false`). Requires Pro plugin.
1552
+ * **Source:** `LicenseHelper.php` (line 657)
1553
+
1554
+ #### Parameters:
1555
+ * `$isStaging` *(bool)* — Whether site is detected as staging
1556
+ * `$url` *(string)* — Site URL being checked
1557
+ * **Returns:** *(bool)* — Modified staging detection result
1558
+
1559
+ #### Usage Example:
1560
+ ```php
1561
+ // Filter final staging site detection boolean result (Pro)
1562
+ add_filter('fluent_cart/license/is_staging_site_result', function ($isStaging, $url) {
1563
+ // Override staging detection for specific target domain string
1564
+ if (str_contains($url, 'mycompany-staging.com')) {
1565
+ return true;
1566
+ }
1567
+ return $isStaging;
1568
+ }, 10, 2);
1569
+ ```
1570
+
1571
+ ---
1572
+
1573
+ ## Pro: License Configuration
1574
+
1575
+ ### `license/validity_by_variation` (Pro)
1576
+ `fluent_cart/license/validity_by_variation` — Filter license validity per variation
1577
+
1578
+ * **When it runs:** Applied when determining license validity settings for a specific product variation. Requires Pro plugin.
1579
+ * **Source:** `ProductLicenseController.php` (line 74)
1580
+
1581
+ #### Parameters:
1582
+ * `$validity` *(array)* — Validity settings array (`duration`, `unit`)
1583
+ * `$context` *(array)* — Context data (`['variation' => ProductVariation]`)
1584
+ * **Returns:** *(array)* — The modified validity settings array
1585
+
1586
+ #### Usage Example:
1587
+ ```php
1588
+ // Filter license validity settings per product variation (Pro)
1589
+ add_filter('fluent_cart/license/validity_by_variation', function ($validity, $context) {
1590
+ // Apply 365-day license validity for premium variation slug
1591
+ $variation = $context['variation'];
1592
+ if ($variation->slug === 'premium') {
1593
+ $validity['duration'] = 365;
1594
+ $validity['unit'] = 'days';
1595
+ }
1596
+ return $validity;
1597
+ }, 10, 2);
1598
+ ```