fluentcart-developer 1.1.0

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 (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,628 @@
1
+ # Filter Hooks: Products & Pricing
2
+
3
+ All filters related to Product display, catalog management, pricing, stock, URLs, and Coupons.
4
+
5
+ ---
6
+
7
+ ## Product Display & Layout
8
+
9
+ ### `products_list`
10
+ `fluent_cart/products_list` — Filter the admin products list
11
+
12
+ * **When it runs:** This filter is applied after fetching the paginated products collection in the admin products list view.
13
+ * **Source:** `app/Http/Controllers/ProductController.php` (line 52)
14
+
15
+ #### Parameters:
16
+ * `$products` *(\FluentCart\Framework\Database\Orm\LengthAwarePaginator)* — Paginated products collection with appended `view_url` and `edit_url` attributes
17
+ * **Returns:** *(\FluentCart\Framework\Database\Orm\LengthAwarePaginator)* — The modified paginated collection
18
+
19
+ #### Usage Example:
20
+ ```php
21
+ // Filter paginated products collection for admin list view
22
+ add_filter('fluent_cart/products_list', function($products) {
23
+ // Loop through collection and attach custom badge attribute
24
+ $products->getCollection()->transform(function ($product) {
25
+ $product->custom_badge = 'Featured';
26
+ return $product;
27
+ });
28
+ return $products;
29
+ }, 10, 1);
30
+ ```
31
+
32
+ ---
33
+
34
+ ### `shop_query`
35
+ `fluent_cart/shop_query` — Filter the shop product query builder
36
+
37
+ * **When it runs:** This filter is applied when building the query for the public-facing shop product listing, before search, status, and sorting clauses are added.
38
+ * **Source:** `api/Resource/ShopResource.php` (line 100)
39
+
40
+ #### Parameters:
41
+ * `$query` *(\FluentCart\Framework\Database\Orm\Builder)* — The Eloquent query builder instance with `select` and `with` already applied
42
+ * `$params` *(array)* — The query parameters array (`select`, `with`, `selected_status`, etc.)
43
+ * **Returns:** *(\FluentCart\Framework\Database\Orm\Builder)* — The modified query builder
44
+
45
+ #### Usage Example:
46
+ ```php
47
+ // Filter shop product query builder before executing search and filters
48
+ add_filter('fluent_cart/shop_query', function($query, $params) {
49
+ // Restrict shop query to products matching category term ID 5
50
+ $query->whereHas('taxonomies', function ($q) {
51
+ $q->where('taxonomy', 'product-category')
52
+ ->where('term_id', 5);
53
+ });
54
+ return $query;
55
+ }, 10, 2);
56
+ ```
57
+
58
+ ---
59
+
60
+ ### `single_product/variation_view_type`
61
+ `fluent_cart/single_product/variation_view_type` — Filter variation display type on single product pages
62
+
63
+ * **When it runs:** This filter is applied when initializing the product renderer to determine how variations are visually presented on the single product page.
64
+ * **Source:** `app/Services/Renderer/ProductRenderer.php` (line 67)
65
+
66
+ #### Parameters:
67
+ * `$viewType` *(string)* — The variation view type (`'image'`, `'text'`, `'both'`)
68
+ * `$data` *(array)* — Context data (`['product' => Product, 'variants' => Collection, 'defaultVariationId' => int]`)
69
+ * **Returns:** *(string)* — The modified view type
70
+
71
+ #### Usage Example:
72
+ ```php
73
+ // Filter variation display type on single product pages
74
+ add_filter('fluent_cart/single_product/variation_view_type', function($viewType, $data) {
75
+ // Force variation display mode to show both image and text
76
+ return 'both';
77
+ }, 10, 2);
78
+ ```
79
+
80
+ ---
81
+
82
+ ### `single_product/variation_column_type`
83
+ `fluent_cart/single_product/variation_column_type` — Filter variation column layout on single product pages
84
+
85
+ * **When it runs:** This filter is applied when initializing the product renderer to determine the column layout for product variations.
86
+ * **Source:** `app/Services/Renderer/ProductRenderer.php` (line 74)
87
+
88
+ #### Parameters:
89
+ * `$columnType` *(string)* — The column layout type (`'one'`, `'two'`, `'three'`, `'four'`, `'masonry'`)
90
+ * `$data` *(array)* — Context data (`['product' => Product, 'variants' => Collection, 'defaultVariationId' => int]`)
91
+ * **Returns:** *(string)* — The modified column type
92
+
93
+ #### Usage Example:
94
+ ```php
95
+ // Filter variation column layout on single product pages
96
+ add_filter('fluent_cart/single_product/variation_column_type', function($columnType, $data) {
97
+ // Extract product model instance from event context
98
+ $product = $data['product'];
99
+
100
+ // Use two-column layout when product has more than 6 variations
101
+ if (count($data['variants']) > 6) {
102
+ return 'two';
103
+ }
104
+ return $columnType;
105
+ }, 10, 2);
106
+ ```
107
+
108
+ ---
109
+
110
+ ### `single_product/variation_price`
111
+ `fluent_cart/single_product/variation_price` — Filter variation price text on single product pages
112
+
113
+ * **When it runs:** This filter is applied when rendering the price text for each product variation. For one-time products the price is the formatted decimal amount; for subscriptions it includes the billing terms text.
114
+ * **Source:** `app/Services/Renderer/ProductRenderer.php` (line 827)
115
+
116
+ #### Parameters:
117
+ * `$priceText` *(string)* — The formatted price text (escaped HTML)
118
+ * `$data` *(array)* — Context data (`['product' => Product, 'variant' => ProductVariant, 'scope' => 'product_variant_price']`)
119
+ * **Returns:** *(string)* — The modified price text (HTML allowed via `wp_kses_post`)
120
+
121
+ #### Usage Example:
122
+ ```php
123
+ // Filter variation price text rendered on single product pages
124
+ add_filter('fluent_cart/single_product/variation_price', function($priceText, $data) {
125
+ // Extract variant model instance
126
+ $variant = $data['variant'];
127
+
128
+ // Append per-month label to subscription variation prices
129
+ if ($variant->payment_type === 'subscription') {
130
+ return $priceText . ' <small>/month</small>';
131
+ }
132
+ return $priceText;
133
+ }, 10, 2);
134
+ ```
135
+
136
+ ---
137
+
138
+ ### `shop_app_product_query_taxonomy_filters`
139
+ `fluent_cart/shop_app_product_query_taxonomy_filters` — Filter taxonomy filters for Shop block product query
140
+
141
+ * **When it runs:** This filter is applied in the Shop App Gutenberg block when merging URL-based taxonomy filters with default block filters, before the product query is executed.
142
+ * **Source:** `app/Hooks/Handlers/BlockEditors/ShopApp/InnerBlocks/InnerBlocks.php` (line 1379)
143
+
144
+ #### Parameters:
145
+ * `$mergedTerms` *(array)* — Merged taxonomy term IDs keyed by taxonomy name (`['product-category' => [1, 5]]`)
146
+ * `$data` *(array)* — Context data (`['default_terms' => [...], 'url_terms' => [...], 'block' => $block]`)
147
+ * **Returns:** *(array)* — The modified taxonomy term IDs array
148
+
149
+ #### Usage Example:
150
+ ```php
151
+ // Filter taxonomy filters for Shop Gutenberg block product query
152
+ add_filter('fluent_cart/shop_app_product_query_taxonomy_filters', function($mergedTerms, $data) {
153
+ // Exclude category ID 99 from shop block product query
154
+ if (isset($mergedTerms['product-category'])) {
155
+ $mergedTerms['product-category'] = array_diff($mergedTerms['product-category'], [99]);
156
+ }
157
+ return $mergedTerms;
158
+ }, 10, 2);
159
+ ```
160
+
161
+ ---
162
+
163
+ ### `products_views/preload_collection_{$provider}`
164
+ `fluent_cart/products_views/preload_collection_{$provider}` — Preload product view collection for a template provider
165
+
166
+ * **When it runs:** This dynamic filter is applied when the shop controller loads products via AJAX for a specific template provider (e.g. `bricks`). The `{$provider}` portion is replaced with the template provider name.
167
+ * **Source:** `app/Http/Controllers/ShopController.php` (line 103)
168
+
169
+ #### Parameters:
170
+ * `$html` *(string)* — Default empty string. Return rendered HTML to use preloaded view instead of JSON
171
+ * `$data` *(array)* — Context data (`['client_id' => string, 'products' => array, 'total' => int, 'requestData' => array]`)
172
+ * **Returns:** *(string)* — Rendered HTML string, or empty string to fall back to default JSON response
173
+
174
+ #### Usage Example:
175
+ ```php
176
+ // Preload product view collection HTML for Bricks template provider
177
+ add_filter('fluent_cart/products_views/preload_collection_bricks', function($html, $data) {
178
+ // Render custom HTML structure for Bricks page builder integration
179
+ ob_start();
180
+ foreach ($data['products'] as $product) {
181
+ echo '<div class="custom-product-card">' . esc_html($product['title']) . '</div>';
182
+ }
183
+ return ob_get_clean();
184
+ }, 10, 2);
185
+ ```
186
+
187
+ ---
188
+
189
+ ## Product Buttons & Text
190
+
191
+ ### `product/buy_now_button_text`
192
+ `fluent_cart/product/buy_now_button_text` — Filter the Buy Now button text
193
+
194
+ * **When it runs:** Applied when rendering the "Buy Now" button on single product pages. Runs in both PHP product renderer and JavaScript variable localization.
195
+ * **Source:** `app/Services/Renderer/ProductRenderer.php` (lines 1081, 1181), `app/Modules/Templating/AssetLoader.php` (lines 87, 261)
196
+
197
+ #### Parameters:
198
+ * `$text` *(string)* — The button text (default: `'Buy Now'`)
199
+ * `$data` *(array)* — Context data (`['product' => Product]`)
200
+ * **Returns:** *(string)* — The modified button text
201
+
202
+ #### Usage Example:
203
+ ```php
204
+ // Filter Buy Now button text on single product pages
205
+ add_filter('fluent_cart/product/buy_now_button_text', function($text, $data) {
206
+ // Customize button text for digital product types
207
+ if (!empty($data['product']) && $data['product']->product_type === 'digital') {
208
+ return 'Download Now';
209
+ }
210
+ return $text;
211
+ }, 10, 2);
212
+ ```
213
+
214
+ ---
215
+
216
+ ### `product/add_to_cart_text`
217
+ `fluent_cart/product/add_to_cart_text` — Filter the Add to Cart button text
218
+
219
+ * **When it runs:** Applied when rendering the "Add to Cart" button text across single product pages, shop blocks, carousels, shortcodes, and localized JS variables.
220
+ * **Source:** `app/Services/Renderer/ProductRenderer.php` (lines 1227, 1314), `app/Hooks/Handlers/ShortCodes/SingleProductShortCode.php` (line 81), `app/Hooks/Handlers/BlockEditors/ShopApp/InnerBlocks/InnerBlocks.php` (lines 1025, 1104)
221
+
222
+ #### Parameters:
223
+ * `$text` *(string)* — The button text (default: `'Add To Cart'`)
224
+ * `$data` *(array)* — Context data (`['product' => Product]`)
225
+ * **Returns:** *(string)* — The modified button text
226
+
227
+ #### Usage Example:
228
+ ```php
229
+ // Filter Add to Cart button text across all product templates
230
+ add_filter('fluent_cart/product/add_to_cart_text', function($text, $data) {
231
+ // Change default Add to Cart button text to Add to Basket
232
+ return 'Add to Basket';
233
+ }, 10, 2);
234
+ ```
235
+
236
+ ---
237
+
238
+ ### `product/out_of_stock_text`
239
+ `fluent_cart/product/out_of_stock_text` — Filter the out-of-stock button text
240
+
241
+ * **When it runs:** Applied when rendering button text for out-of-stock products across shortcodes, shop blocks, carousels, and localized JS variables.
242
+ * **Source:** `app/Hooks/Handlers/ShortCodes/SingleProductShortCode.php` (line 83), `app/Hooks/Handlers/BlockEditors/ShopApp/InnerBlocks/InnerBlocks.php` (lines 1027, 1106)
243
+
244
+ #### Parameters:
245
+ * `$text` *(string)* — The out-of-stock text (default: `'Not Available'`)
246
+ * `$data` *(array)* — Context data (empty array)
247
+ * **Returns:** *(string)* — The modified out-of-stock text
248
+
249
+ #### Usage Example:
250
+ ```php
251
+ // Filter out-of-stock button text for unavailable products
252
+ add_filter('fluent_cart/product/out_of_stock_text', function($text) {
253
+ // Override out-of-stock label text
254
+ return 'Sold Out';
255
+ }, 10, 1);
256
+ ```
257
+
258
+ ---
259
+
260
+ ### `product/out_of_stock_button_text`
261
+ `fluent_cart/product/out_of_stock_button_text` — Filter out-of-stock button text (block editor context)
262
+
263
+ * **When it runs:** Applied in block editor asset loader when localizing out-of-stock button text for JS-rendered product pages.
264
+ * **Source:** `app/Modules/Templating/AssetLoader.php` (line 260)
265
+
266
+ #### Parameters:
267
+ * `$text` *(string)* — The out-of-stock text (default: `'Not Available'`)
268
+ * `$data` *(array)* — Context data (empty array)
269
+ * **Returns:** *(string)* — The modified button text
270
+
271
+ #### Usage Example:
272
+ ```php
273
+ // Filter out-of-stock button text in block editor asset loader
274
+ add_filter('fluent_cart/product/out_of_stock_button_text', function($text) {
275
+ // Customize out-of-stock label for JS-rendered pages
276
+ return 'Currently Unavailable';
277
+ }, 10, 1);
278
+ ```
279
+
280
+ ---
281
+
282
+ ### `product/price_suffix_atts`
283
+ `fluent_cart/product/price_suffix_atts` — Filter price suffix for product variations
284
+
285
+ * **When it runs:** Applied when rendering each variation item in the selector. Tax module hooks here to append tax suffixes (e.g. "incl. tax").
286
+ * **Source:** `app/Services/Renderer/ProductRenderer.php` (line 1408)
287
+
288
+ #### Parameters:
289
+ * `$suffix` *(string)* — The price suffix text (default: `''`)
290
+ * `$data` *(array)* — Context data (`['product' => Product, 'variant' => ProductVariant, 'scope' => 'variant_item']`)
291
+ * **Returns:** *(string)* — The modified price suffix text
292
+
293
+ #### Usage Example:
294
+ ```php
295
+ // Filter price suffix text for product variations
296
+ add_filter('fluent_cart/product/price_suffix_atts', function($suffix, $data) {
297
+ // Append custom tax suffix label to variation price
298
+ return ' incl. VAT';
299
+ }, 10, 2);
300
+ ```
301
+
302
+ ---
303
+
304
+ ### `product_short_description`
305
+ `fluent_cart/product_short_description` — Filter product short description
306
+
307
+ * **When it runs:** Applied when rendering short description on single product page, using post excerpt as default value.
308
+ * **Source:** `app/Hooks/Handlers/TemplateLoader.php` (line 26)
309
+
310
+ #### Parameters:
311
+ * `$shortDescription` *(string)* — Product short description (from `$post->post_excerpt`)
312
+ * `$data` *(array)* — Context data (empty array)
313
+ * **Returns:** *(string)* — Modified short description (output via `wp_kses_post`)
314
+
315
+ #### Usage Example:
316
+ ```php
317
+ // Filter product short description output on single product pages
318
+ add_filter('fluent_cart/product_short_description', function($shortDescription) {
319
+ // Append price disclaimer paragraph to short description
320
+ return $shortDescription . '<p class="disclaimer">Prices subject to change.</p>';
321
+ }, 10, 1);
322
+ ```
323
+
324
+ ---
325
+
326
+ ## Stock & Availability
327
+
328
+ ### `product_stock_availability`
329
+ `fluent_cart/product_stock_availability` — Filter product stock availability information
330
+
331
+ * **When it runs:** Applied when retrieving stock availability data from `ProductDetail` model, based on stock settings and inventory levels.
332
+ * **Source:** `app/Models/ProductDetail.php` (line 183)
333
+
334
+ #### Parameters:
335
+ * `$availability` *(array)* — Stock availability data (`manage_stock`, `availability`, `class`, `available_quantity`)
336
+ * `$data` *(array)* — Context data (`['detail' => ProductDetail, 'variation_id' => int|null]`)
337
+ * **Returns:** *(array)* — The modified availability data
338
+
339
+ #### Usage Example:
340
+ ```php
341
+ // Filter product stock availability status data and label
342
+ add_filter('fluent_cart/product_stock_availability', function($availability, $data) {
343
+ // Show low stock warning message when quantity is under 5
344
+ if ($availability['manage_stock'] && $availability['available_quantity'] > 0 && $availability['available_quantity'] < 5) {
345
+ $availability['availability'] = 'Only ' . $availability['available_quantity'] . ' left in stock!';
346
+ $availability['class'] = 'low-stock';
347
+ }
348
+ return $availability;
349
+ }, 10, 2);
350
+ ```
351
+
352
+ ---
353
+
354
+ ## Product URLs & Templates
355
+
356
+ ### `price_class`
357
+ `fluent_cart/price_class` — Filter price element CSS class
358
+
359
+ * **When it runs:** Applied when rendering the price paragraph element on the single product page template.
360
+ * **Source:** `app/Hooks/Handlers/TemplateLoader.php` (line 40)
361
+
362
+ #### Parameters:
363
+ * `$class` *(string)* — The CSS class for price element (default: `'price'`)
364
+ * **Returns:** *(string)* — The modified CSS class string
365
+
366
+ #### Usage Example:
367
+ ```php
368
+ // Filter price paragraph element CSS class on single product page
369
+ add_filter('fluent_cart/price_class', function($class) {
370
+ // Add custom CSS class to price container element
371
+ return 'price fct-custom-price';
372
+ }, 10, 1);
373
+ ```
374
+
375
+ ---
376
+
377
+ ### `front_url_slug`
378
+ `fluent_cart/front_url_slug` — Filter product URL slug
379
+
380
+ * **When it runs:** Applied when registering `fluent-products` CPT to change URL slug for permalinks. Default comes from store settings (`'item'`).
381
+ * **Source:** `app/CPT/FluentProducts.php` (line 181)
382
+
383
+ #### Parameters:
384
+ * `$slug` *(string)* — Product URL slug
385
+ * `$data` *(array)* — Context data (empty array)
386
+ * **Returns:** *(string)* — Modified URL slug
387
+
388
+ #### Usage Example:
389
+ ```php
390
+ // Filter product custom post type URL permalink slug
391
+ add_filter('fluent_cart/front_url_slug', function($slug) {
392
+ // Change product permalink base slug from item to shop
393
+ return 'shop';
394
+ }, 10, 1);
395
+ ```
396
+
397
+ ---
398
+
399
+ ### `product_url_with_front`
400
+ `fluent_cart/product_url_with_front` — Filter whether product URL includes front base
401
+
402
+ * **When it runs:** Applied when registering `fluent-products` CPT rewrite rules. Controls whether permalink front base (e.g. `/blog/`) is prepended.
403
+ * **Source:** `app/CPT/FluentProducts.php` (line 183)
404
+
405
+ #### Parameters:
406
+ * `$withFront` *(bool)* — Whether to prepend permalink front base (default: `true`)
407
+ * `$data` *(array)* — Context data (`['slug' => string]`)
408
+ * **Returns:** *(bool)* — Modified boolean value
409
+
410
+ #### Usage Example:
411
+ ```php
412
+ // Filter whether product permalinks include site front base prefix
413
+ add_filter('fluent_cart/product_url_with_front', function($withFront, $data) {
414
+ // Remove permalink front base from product URLs
415
+ return false;
416
+ }, 10, 2);
417
+ ```
418
+
419
+ ---
420
+
421
+ ### `show_standalone_product_menu`
422
+ `fluent_cart/show_standalone_product_menu` — Filter whether to show standalone Products menu in WP admin
423
+
424
+ * **When it runs:** Applied during init when registering `fluent-products` CPT. When enabled, adds a separate "Products" sidebar menu.
425
+ * **Source:** `app/CPT/FluentProducts.php` (line 37)
426
+
427
+ #### Parameters:
428
+ * `$show` *(bool)* — Whether to show standalone menu (default: `false`)
429
+ * **Returns:** *(bool)* — Modified boolean value
430
+
431
+ #### Usage Example:
432
+ ```php
433
+ // Filter whether to display standalone Products menu in WP admin sidebar
434
+ add_filter('fluent_cart/show_standalone_product_menu', function($show) {
435
+ // Enable standalone Products CPT menu in WP admin
436
+ return true;
437
+ }, 10, 1);
438
+ ```
439
+
440
+ ---
441
+
442
+ ### `single_product_page/show_relevant_products`
443
+ `fluent_cart/single_product_page/show_relevant_products` — Filter showing related products on single product page
444
+
445
+ * **When it runs:** Applied when rendering single product page content after checking `show_relevant_product_in_single_page` store setting.
446
+ * **Source:** `app/Modules/Templating/TemplateActions.php` (line 240)
447
+
448
+ #### Parameters:
449
+ * `$show` *(bool)* — Whether to show related products
450
+ * `$postId` *(int)* — Current product post ID
451
+ * **Returns:** *(bool)* — Modified boolean value
452
+
453
+ #### Usage Example:
454
+ ```php
455
+ // Filter whether to show related products section on single product page
456
+ add_filter('fluent_cart/single_product_page/show_relevant_products', function($show, $postId) {
457
+ // Hide related products for specific product IDs
458
+ $excludedIds = [100, 200, 300];
459
+ if (in_array($postId, $excludedIds)) {
460
+ return false;
461
+ }
462
+ return $show;
463
+ }, 10, 2);
464
+ ```
465
+
466
+ ---
467
+
468
+ ### `disable_auto_single_product_page`
469
+ `fluent_cart/disable_auto_single_product_page` — Disable automatic single product page rendering
470
+
471
+ * **When it runs:** Applied when filtering title and content for single product pages. When true, prevents FluentCart from auto-injecting layout HTML.
472
+ * **Source:** `app/Modules/Templating/TemplateActions.php` (lines 191, 215)
473
+
474
+ #### Parameters:
475
+ * `$disable` *(bool)* — Whether to disable auto-rendering (default: `false`)
476
+ * **Returns:** *(bool)* — Modified boolean value
477
+
478
+ #### Usage Example:
479
+ ```php
480
+ // Filter whether to disable automatic single product page template rendering
481
+ add_filter('fluent_cart/disable_auto_single_product_page', function($disable) {
482
+ // Disable automatic rendering when Elementor page builder is active
483
+ if (class_exists('Elementor\Plugin')) {
484
+ return true;
485
+ }
486
+ return $disable;
487
+ }, 10, 1);
488
+ ```
489
+
490
+ ---
491
+
492
+ ## Coupons
493
+
494
+ ### `coupon/validating_coupon`
495
+ `fluent_cart/coupon/validating_coupon` — Filter coupon code during validation
496
+
497
+ * **When it runs:** Applied at the start of coupon validation before database lookup. Modify code string or return `WP_Error` to reject.
498
+ * **Source:** `app/Services/Coupon/Concerns/CanValidateCoupon.php` (line 21)
499
+
500
+ #### Parameters:
501
+ * `$couponCode` *(string)* — Coupon code being validated
502
+ * `$data` *(array)* — Context data (`['coupon_code' => string, 'line_items' => array, 'couponService' => CouponService]`)
503
+ * **Returns:** *(string|\WP_Error)* — Modified coupon code, or `WP_Error` to reject
504
+
505
+ #### Usage Example:
506
+ ```php
507
+ // Filter coupon code string at start of validation
508
+ add_filter('fluent_cart/coupon/validating_coupon', function($couponCode, $data) {
509
+ // Normalize coupon code string to uppercase
510
+ $couponCode = strtoupper(trim($couponCode));
511
+
512
+ // Reject blocked coupon codes with error message
513
+ $blockedCodes = ['EXPIRED2024', 'TESTONLY'];
514
+ if (in_array($couponCode, $blockedCodes)) {
515
+ return new \WP_Error('coupon_blocked', __('This coupon code is no longer valid.', 'fluent-cart'));
516
+ }
517
+
518
+ return $couponCode;
519
+ }, 10, 2);
520
+ ```
521
+
522
+ ---
523
+
524
+ ### `coupon/can_use_coupon`
525
+ `fluent_cart/coupon/can_use_coupon` — Filter whether a coupon can be used
526
+
527
+ * **When it runs:** Applied after coupon is found in database but before discount calculation to run custom eligibility checks.
528
+ * **Source:** `app/Services/Coupon/DiscountService.php` (line 257)
529
+
530
+ #### Parameters:
531
+ * `$canUse` *(bool)* — Whether coupon can be used (default: `true`)
532
+ * `$data` *(array)* — Context data (`['coupon' => Coupon, 'cart' => Cart, 'cart_items' => array]`)
533
+ * **Returns:** *(bool|\WP_Error)* — `true` to allow, `false` or `WP_Error` to reject
534
+
535
+ #### Usage Example:
536
+ ```php
537
+ // Filter whether a validated coupon can be applied to current cart
538
+ add_filter('fluent_cart/coupon/can_use_coupon', function($canUse, $data) {
539
+ // Extract coupon model and cart model from context
540
+ $coupon = $data['coupon'];
541
+ $cart = $data['cart'];
542
+
543
+ // Enforce minimum cart subtotal requirement of $50
544
+ if ($cart->sub_total < 5000) {
545
+ return new \WP_Error(
546
+ 'coupon_min_total',
547
+ __('This coupon requires a minimum order of $50.', 'fluent-cart')
548
+ );
549
+ }
550
+
551
+ return $canUse;
552
+ }, 10, 2);
553
+ ```
554
+
555
+ ---
556
+
557
+ ### `coupon/will_skip_item`
558
+ `fluent_cart/coupon/will_skip_item` — Filter whether item is skipped from coupon discount
559
+
560
+ * **When it runs:** Applied for each cart item when filtering applicable items. Returning true excludes item from discount calculation.
561
+ * **Source:** `app/Services/Coupon/DiscountService.php` (line 279)
562
+
563
+ #### Parameters:
564
+ * `$willSkip` *(bool)* — Whether to skip item (default: `false`)
565
+ * `$data` *(array)* — Context data (`['item' => array, 'coupon' => Coupon, 'cart' => Cart]`)
566
+ * **Returns:** *(bool)* — `true` to exclude item from coupon discount
567
+
568
+ #### Usage Example:
569
+ ```php
570
+ // Filter whether specific cart item is skipped from coupon discount
571
+ add_filter('fluent_cart/coupon/will_skip_item', function($willSkip, $data) {
572
+ // Extract cart item array from context
573
+ $item = $data['item'];
574
+
575
+ // Exclude gift card product types from coupon discount calculation
576
+ if (!empty($item['product_type']) && $item['product_type'] === 'gift_card') {
577
+ return true;
578
+ }
579
+
580
+ return $willSkip;
581
+ }, 10, 2);
582
+ ```
583
+
584
+ ---
585
+
586
+ ### `coupon/per_customer_usage_query`
587
+ `fluent_cart/coupon/per_customer_usage_query` — Filter per-customer coupon usage query
588
+
589
+ * **When it runs:** Applied when checking if customer exceeded per-customer usage limit for coupon to modify previous usage count query.
590
+ * **Source:** `app/Services/Coupon/DiscountService.php` (line 592)
591
+
592
+ #### Parameters:
593
+ * `$usageQuery` *(\FluentCart\Framework\Database\Orm\Builder)* — Eloquent query builder for `AppliedCoupon` records
594
+ * `$data` *(array)* — Context data (`['coupon' => Coupon, 'customer' => Customer, 'cart' => Cart]`)
595
+ * **Returns:** *(\FluentCart\Framework\Database\Orm\Builder)* — Modified query builder
596
+
597
+ #### Usage Example:
598
+ ```php
599
+ // Filter per-customer coupon usage limit Eloquent query
600
+ add_filter('fluent_cart/coupon/per_customer_usage_query', function($usageQuery, $data) {
601
+ // Restrict usage check query to last 30 days for rolling limits
602
+ $usageQuery->where('created_at', '>=', gmdate('Y-m-d H:i:s', strtotime('-30 days')));
603
+ return $usageQuery;
604
+ }, 10, 2);
605
+ ```
606
+
607
+ ---
608
+
609
+ ### `coupon_statuses` (legacy)
610
+ `fluent-cart/coupon_statuses` — Filter available coupon statuses
611
+
612
+ * **When it runs:** Applied when retrieving available coupon statuses for admin coupon management interface. Note hyphenated prefix (`fluent-cart/`).
613
+ * **Source:** `app/Helpers/Helper.php` (line 823)
614
+
615
+ #### Parameters:
616
+ * `$statuses` *(array)* — Array of coupon statuses (`'active' => 'Active'`, `'expired' => 'Expired'`, `'disabled' => 'Disabled'`)
617
+ * `$data` *(array)* — Context data (empty array)
618
+ * **Returns:** *(array)* — Modified coupon statuses array
619
+
620
+ #### Usage Example:
621
+ ```php
622
+ // Filter available coupon statuses array (legacy hyphenated hook name)
623
+ add_filter('fluent-cart/coupon_statuses', function($statuses) {
624
+ // Add custom "Scheduled" coupon status
625
+ $statuses['scheduled'] = __('Scheduled', 'fluent-cart');
626
+ return $statuses;
627
+ }, 10, 1);
628
+ ```