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,604 @@
1
+ # FluentCart Eloquent Models Master Reference
2
+
3
+ > Source: Official FluentCart Developer Documentation
4
+
5
+ Complete technical developer reference for FluentCart's Eloquent ORM Models. Covers attributes, mutators, accessors, relationships, scopes, helper methods, and query patterns across Core and Pro models.
6
+
7
+ ---
8
+
9
+ ## 💡 Core Architecture Rules
10
+
11
+ 1. **Namespaces:**
12
+ - Core Models: `\FluentCart\App\Models\*`
13
+ - Pro Models: `\FluentCartPro\App\Models\*` or module-specific namespaces like `\FluentCartPro\App\Modules\Licensing\Models\*` and `\FluentCartPro\App\Modules\Promotional\Models\*`.
14
+ 2. **Cents Precision:**
15
+ - Financial attributes (`total_amount`, `subtotal`, `tax_total`, `discount_total`, `unit_price`, `cost`, `line_total`, `refund_total`, `total_paid`, `amount`) are stored in **cents** as integers or double precision floats.
16
+ - Use `\FluentCart\App\Helpers\Helper::toDecimal($cents)` when displaying decimal strings.
17
+ - Use `\FluentCart\App\Helpers\Helper::toCent($decimal)` when saving decimal user inputs.
18
+
19
+ ---
20
+
21
+ ## 1. Core Order Models
22
+
23
+ ### `Order` (`\FluentCart\App\Models\Order`)
24
+ * **Database Table:** `{wp_db_prefix}_fct_orders`
25
+ * **Source File:** `fluent-cart/app/Models/Order.php`
26
+
27
+ | Attribute | Type | Description / Cast |
28
+ |---|---|---|
29
+ | `id` | Integer | Primary key ID |
30
+ | `status` | String | Order status (`draft`, `pending`, `processing`, `completed`, `on-hold`, `failed`, `refunded`, `partial-refund`) |
31
+ | `parent_id` | Integer | Parent order ID (for renewal / child orders) |
32
+ | `receipt_number` | Integer | Order receipt number |
33
+ | `invoice_no` | String | Order invoice number |
34
+ | `fulfillment_type` | String | Fulfillment type (`physical`, `digital`, `service`, `mixed`) |
35
+ | `type` | String | Order type (`payment`, `renewal`, `refund`) |
36
+ | `mode` | String | Gateway mode (`live`, `test`) |
37
+ | `shipping_status` | String | Shipping status (`unshipped`, `shipped`, `delivered`, `unshippable`) |
38
+ | `customer_id` | Integer | Reference to customer ID |
39
+ | `payment_method` | String | Payment gateway key (e.g. `stripe`, `paypal`) |
40
+ | `payment_status` | String | Payment status (`paid`, `unpaid`, `refunded`, `partially_refunded`) |
41
+ | `payment_method_title` | String | Display title of payment method |
42
+ | `currency` | String | 3-letter currency code (e.g. `USD`) |
43
+ | `subtotal` | Integer | Order subtotal in cents |
44
+ | `discount_tax` | Integer | Discount tax in cents |
45
+ | `manual_discount_total` | Integer | Manual discount in cents |
46
+ | `coupon_discount_total` | Integer | Coupon discount total in cents |
47
+ | `shipping_tax` | Integer | Shipping tax in cents |
48
+ | `shipping_total` | Integer | Shipping total in cents |
49
+ | `tax_total` | Integer | Tax total in cents |
50
+ | `total_amount` | Integer | Total order amount in cents |
51
+ | `total_paid` | Integer | Total paid amount in cents |
52
+ | `total_refund` | Integer | Total refunded amount in cents |
53
+ | `rate` | Decimal | Exchange rate |
54
+ | `tax_behavior` | Integer | Tax behavior (`0` = no tax, `1` = exclusive, `2` = inclusive) |
55
+ | `note` | Text | Order internal notes |
56
+ | `ip_address` | Text | Customer IP address |
57
+ | `completed_at` | DateTime | Completion timestamp |
58
+ | `refunded_at` | DateTime | Refund timestamp |
59
+ | `uuid` | String | Unique public identifier |
60
+ | `config` | JSON | Configuration options array (auto JSON encoded/decoded) |
61
+
62
+ ```php
63
+ // Retrieve order by primary key ID
64
+ $order = \FluentCart\App\Models\Order::find(1);
65
+
66
+ // Update order status slug
67
+ $order->updateStatus('status', 'completed');
68
+
69
+ // Update payment status slug
70
+ $order->updatePaymentStatus('paid');
71
+
72
+ // Fetch order meta value with fallback
73
+ $customVal = $order->getMeta('custom_key', 'default_value');
74
+
75
+ // Recount total paid and total refund amounts, updating payment status
76
+ $order->recountTotalPaidAndRefund();
77
+
78
+ // Add activity log to order timeline
79
+ $order->addLog('Status Updated', 'Order status changed to completed', 'info', 'admin');
80
+ ```
81
+
82
+ ---
83
+
84
+ ### `OrderItem` (`\FluentCart\App\Models\OrderItem`)
85
+ * **Database Table:** `{wp_db_prefix}_fct_order_items`
86
+ * **Source File:** `fluent-cart/app/Models/OrderItem.php`
87
+
88
+ | Attribute | Type | Description / Cast |
89
+ |---|---|---|
90
+ | `id` | Integer | Primary key ID |
91
+ | `order_id` | Integer | Reference to parent order |
92
+ | `post_id` | Integer | WordPress post ID (product) |
93
+ | `fulfillment_type` | String | Fulfillment type (`physical`, `digital`, `service`) |
94
+ | `title` | Text | Variation title |
95
+ | `quantity` | Integer | Item quantity |
96
+ | `unit_price` | Double | Price per unit in cents (cast to double) |
97
+ | `subtotal` | Double | Line subtotal in cents (cast to double) |
98
+ | `line_total` | Double | Total line amount in cents (cast to double) |
99
+ | `other_info` | JSON | Array of additional item options (auto encoded/decoded) |
100
+
101
+ ```php
102
+ // Retrieve line item by ID
103
+ $item = \FluentCart\App\Models\OrderItem::find(1);
104
+
105
+ // Access parent order relationship
106
+ $order = $item->order;
107
+
108
+ // Access associated catalog product
109
+ $product = $item->product;
110
+
111
+ // Access product variation instance
112
+ $variation = $item->variants;
113
+ ```
114
+
115
+ ---
116
+
117
+ ### `OrderMeta` (`\FluentCart\App\Models\OrderMeta`)
118
+ * **Database Table:** `{wp_db_prefix}_fct_order_meta`
119
+ * **Source File:** `fluent-cart/app/Models/OrderMeta.php`
120
+
121
+ ```php
122
+ // Retrieve order meta by primary key
123
+ $orderMeta = \FluentCart\App\Models\OrderMeta::find(1);
124
+
125
+ // Update or create order meta entry
126
+ $orderMeta->updateMeta('shipping_notes', 'Leave package at front porch');
127
+ ```
128
+
129
+ ---
130
+
131
+ ### `OrderTransaction` (`\FluentCart\App\Models\OrderTransaction`)
132
+ * **Database Table:** `{wp_db_prefix}_fct_order_transactions`
133
+ * **Source File:** `fluent-cart/app/Models/OrderTransaction.php`
134
+
135
+ ```php
136
+ // Retrieve order transaction by ID
137
+ $transaction = \FluentCart\App\Models\OrderTransaction::find(1);
138
+
139
+ // Filter transactions by succeeded status
140
+ $succeededTrxs = \FluentCart\App\Models\OrderTransaction::ofStatus('succeeded')->get();
141
+
142
+ // Calculate maximum remaining refundable amount in cents
143
+ $maxRefundCents = $transaction->getMaxRefundableAmount();
144
+ ```
145
+
146
+ ---
147
+
148
+ ### `OrderAddress` (`\FluentCart\App\Models\OrderAddress`)
149
+ * **Database Table:** `{wp_db_prefix}_fct_order_addresses`
150
+ * **Source File:** `fluent-cart/app/Models/OrderAddress.php`
151
+
152
+ ```php
153
+ // Retrieve order address model by ID
154
+ $address = \FluentCart\App\Models\OrderAddress::find(1);
155
+
156
+ // Get formatted plain text address string
157
+ $textAddress = $address->getAddressAsText(false, true, ', ');
158
+ ```
159
+
160
+ ---
161
+
162
+ ## 2. Attribute System Models
163
+
164
+ ### `AttributeGroup` (`\FluentCart\App\Models\AttributeGroup`)
165
+ * **Database Table:** `{wp_db_prefix}_fct_atts_groups`
166
+ * **Source File:** `fluent-cart/app/Models/AttributeGroup.php`
167
+ * **Traits:** `CanSearch` (`search()`, `groupSearch()`, `whereLike()`, `whereBeginsWith()`, `whereEndsWith()`)
168
+
169
+ | Attribute | Type | Description |
170
+ |---|---|---|
171
+ | `id` | Integer | Primary Key |
172
+ | `title` | String | Attribute group title (e.g., Color, Size) |
173
+ | `slug` | String | Attribute group slug |
174
+ | `description` | Text | Attribute group description |
175
+ | `settings` | JSON | Attribute group settings array (auto encoded/decoded) |
176
+
177
+ ```php
178
+ // Create a new attribute group with JSON settings
179
+ $attributeGroup = \FluentCart\App\Models\AttributeGroup::create([
180
+ 'title' => 'Color',
181
+ 'slug' => 'color',
182
+ 'description' => 'Product color variations',
183
+ 'settings' => [
184
+ 'display_type' => 'dropdown',
185
+ 'required' => true,
186
+ 'multiple' => false
187
+ ]
188
+ ]);
189
+
190
+ // Eager load group with its terms
191
+ $groupsWithTerms = \FluentCart\App\Models\AttributeGroup::with('terms')->get();
192
+ ```
193
+
194
+ ---
195
+
196
+ ### `AttributeTerm` (`\FluentCart\App\Models\AttributeTerm`)
197
+ * **Database Table:** `{wp_db_prefix}_fct_atts_terms`
198
+ * **Source File:** `fluent-cart/app/Models/AttributeTerm.php`
199
+ * **Traits:** `CanSearch`
200
+
201
+ | Attribute | Type | Description |
202
+ |---|---|---|
203
+ | `id` | Integer | Primary Key |
204
+ | `group_id` | Integer | Reference to attribute group ID |
205
+ | `serial` | Integer | Serial number for ordering terms |
206
+ | `title` | String | Attribute term title (e.g., Red, Small) |
207
+ | `slug` | String | Attribute term slug |
208
+ | `description` | Text | Attribute term description |
209
+ | `settings` | JSON | Attribute term settings array (auto encoded/decoded) |
210
+
211
+ ```php
212
+ // Create a new attribute term linked to a group
213
+ $term = \FluentCart\App\Models\AttributeTerm::create([
214
+ 'group_id' => 1, // Color group ID
215
+ 'serial' => 1, // Display order
216
+ 'title' => 'Red',
217
+ 'slug' => 'red',
218
+ 'description' => 'Red color variant',
219
+ 'settings' => [
220
+ 'color_code' => '#FF0000',
221
+ 'display_order' => 1
222
+ ]
223
+ ]);
224
+ ```
225
+
226
+ ---
227
+
228
+ ### `AttributeRelation` (`\FluentCart\App\Models\AttributeRelation`)
229
+ * **Database Table:** `{wp_db_prefix}_fct_atts_relations`
230
+ * **Source File:** `fluent-cart/app/Models/AttributeRelation.php`
231
+
232
+ | Attribute | Type | Description |
233
+ |---|---|---|
234
+ | `id` | Integer | Primary Key |
235
+ | `group_id` | Integer | Reference to attribute group ID |
236
+ | `term_id` | Integer | Reference to attribute term ID |
237
+ | `object_id` | Integer | Reference to product variation / detail ID |
238
+
239
+ ```php
240
+ // Attach attribute term to a product detail / variation
241
+ $relation = \FluentCart\App\Models\AttributeRelation::create([
242
+ 'group_id' => 1, // Color group ID
243
+ 'term_id' => 5, // Red term ID
244
+ 'object_id' => 123 // Product variation / detail ID
245
+ ]);
246
+ ```
247
+
248
+ ---
249
+
250
+ ## 3. Shipping & Tax Models
251
+
252
+ ### `ShippingZone` (`\FluentCart\App\Models\ShippingZone`)
253
+ * **Database Table:** `{wp_db_prefix}_fct_shipping_zones`
254
+ * **Source File:** `fluent-cart/app/Models/ShippingZone.php`
255
+
256
+ ```php
257
+ // Create shipping zone for North America
258
+ $zone = \FluentCart\App\Models\ShippingZone::create([
259
+ 'name' => 'United States',
260
+ 'region' => 'US',
261
+ 'order' => 1
262
+ ]);
263
+ ```
264
+
265
+ ---
266
+
267
+ ### `ShippingMethod` (`\FluentCart\App\Models\ShippingMethod`)
268
+ * **Database Table:** `{wp_db_prefix}_fct_shipping_methods`
269
+ * **Source File:** `fluent-cart/app/Models/ShippingMethod.php`
270
+
271
+ ```php
272
+ // Filter shipping methods applicable to US, California
273
+ $availableMethods = \FluentCart\App\Models\ShippingMethod::applicableToCountry('US', 'CA')->get();
274
+ ```
275
+
276
+ ---
277
+
278
+ ### `ShippingClass` (`\FluentCart\App\Models\ShippingClass`)
279
+ * **Database Table:** `{wp_db_prefix}_fct_shipping_classes`
280
+ * **Source File:** `fluent-cart/app/Models/ShippingClass.php`
281
+
282
+ ```php
283
+ // Create heavy item shipping class
284
+ $class = \FluentCart\App\Models\ShippingClass::create([
285
+ 'name' => 'Heavy Freight',
286
+ 'cost' => 25.00,
287
+ 'type' => 'freight',
288
+ 'per_item' => true
289
+ ]);
290
+ ```
291
+
292
+ ---
293
+
294
+ ### `TaxClass` (`\FluentCart\App\Models\TaxClass`)
295
+ * **Database Table:** `{wp_db_prefix}_fct_tax_classes`
296
+ * **Source File:** `fluent-cart/app/Models/TaxClass.php`
297
+
298
+ ```php
299
+ // Create tax class (slug will be auto-generated as "reduced-tax-rate")
300
+ $taxClass = \FluentCart\App\Models\TaxClass::create([
301
+ 'title' => 'Reduced Tax Rate',
302
+ 'meta' => ['rate' => 5.0]
303
+ ]);
304
+ ```
305
+
306
+ ---
307
+
308
+ ### `TaxRate` (`\FluentCart\App\Models\TaxRate`)
309
+ * **Database Table:** `{wp_db_prefix}_fct_tax_rates`
310
+ * **Source File:** `fluent-cart/app/Models/TaxRate.php`
311
+ * **Timestamps:** Disabled (`$timestamps = false`)
312
+
313
+ ```php
314
+ // Create tax rate rule for California
315
+ $taxRate = \FluentCart\App\Models\TaxRate::create([
316
+ 'class_id' => 1,
317
+ 'country' => 'US',
318
+ 'state' => 'CA',
319
+ 'rate' => 8.75,
320
+ 'name' => 'California Sales Tax',
321
+ 'priority' => 1,
322
+ 'is_compound' => false,
323
+ 'for_order' => true
324
+ ]);
325
+ ```
326
+
327
+ ---
328
+
329
+ ## 4. Label System Models
330
+
331
+ ### `Label` (`\FluentCart\App\Models\Label`)
332
+ * **Database Table:** `{wp_db_prefix}_fct_label`
333
+ * **Source File:** `fluent-cart/app/Models/Label.php`
334
+
335
+ ```php
336
+ // Create label with array value (automatically serialized)
337
+ $label = \FluentCart\App\Models\Label::create([
338
+ 'value' => [
339
+ 'name' => 'VIP Customer',
340
+ 'color' => 'gold'
341
+ ]
342
+ ]);
343
+ ```
344
+
345
+ ---
346
+
347
+ ### `LabelRelationship` (`\FluentCart\App\Models\LabelRelationship`)
348
+ * **Database Table:** `{wp_db_prefix}_fct_label_relationships`
349
+ * **Source File:** `fluent-cart/app/Models/LabelRelationship.php`
350
+
351
+ ```php
352
+ // Access polymorphic morphTo relationship on labelable model
353
+ $relationship = \FluentCart\App\Models\LabelRelationship::find(1);
354
+ $targetObject = $relationship->labelable;
355
+ ```
356
+
357
+ ---
358
+
359
+ ## 5. Pro Plugin Models (FluentCart Pro)
360
+
361
+ ### `License` (`\FluentCartPro\App\Modules\Licensing\Models\License`)
362
+ * **Database Table:** `{wp_db_prefix}_fct_licenses`
363
+ * **Source File:** `fluent-cart-pro/app/Modules/Licensing/Models/License.php`
364
+ * **Plugin:** FluentCart Pro
365
+ * **Traits:** `CanSearch`
366
+
367
+ | Attribute | Type | Description / Cast |
368
+ |---|---|---|
369
+ | `id` | Integer | Primary key ID (guarded) |
370
+ | `status` | String | License status (`active`, `inactive`, `expired`, `disabled`) |
371
+ | `limit` | Integer | Activation limit (`0` = unlimited) |
372
+ | `activation_count` | Integer | Current activation count |
373
+ | `license_key` | String | Unique software license key |
374
+ | `product_id` | Integer | Reference to catalog product |
375
+ | `variation_id` | Integer | Reference to product variation |
376
+ | `order_id` | Integer | Reference to order |
377
+ | `parent_id` | Integer | Parent license ID (for renewals) |
378
+ | `customer_id` | Integer | Reference to customer |
379
+ | `expiration_date` | DateTime | License expiration date (`null` = lifetime) |
380
+ | `last_reminder_sent` | DateTime | Timestamp of last reminder |
381
+ | `last_reminder_type` | String | Reminder type slug |
382
+ | `subscription_id` | Integer | Reference to subscription |
383
+ | `config` | JSON | Configuration options array (auto JSON encoded/decoded) |
384
+
385
+ #### Relationships
386
+ - `customer` *(belongsTo)* -> `Customer`
387
+ - `order` *(belongsTo)* -> `Order`
388
+ - `product` *(belongsTo)* -> `Product`
389
+ - `variation` / `productVariant` *(belongsTo)* -> `ProductVariation`
390
+ - `productDetails` *(belongsTo)* -> `ProductDetail`
391
+ - `subscription` *(belongsTo)* -> `Subscription`
392
+ - `activations` *(hasMany)* -> `LicenseActivation`
393
+ - `labels` *(morphMany)* -> `LabelRelationship`
394
+
395
+ #### Query Scopes & Helper Methods
396
+ ```php
397
+ // Search across license keys, order IDs, product titles, and customer email
398
+ $licenses = \FluentCartPro\App\Modules\Licensing\Models\License::search('john@example.com')->get();
399
+
400
+ // Smart status scope filtering: active, expired, inactive, or disabled
401
+ $activeLicenses = \FluentCartPro\App\Modules\Licensing\Models\License::status('active')->get();
402
+
403
+ // Filter licenses by array of product IDs
404
+ $prodLicenses = \FluentCartPro\App\Modules\Licensing\Models\License::products([1, 2, 3])->get();
405
+
406
+ // Helper method checks
407
+ $license = \FluentCartPro\App\Modules\Licensing\Models\License::find(1);
408
+ $isActive = $license->isActive(); // True if active or inactive
409
+ $isExpired = $license->isExpired(); // Checks expiration date & grace period
410
+ $isValid = $license->isValid(); // True if active and not expired
411
+
412
+ // Management helper methods (fires action hooks)
413
+ $license->updateLicenseStatus('disabled'); // Triggers fluent_cart_sl/license_status_updated
414
+ $license->increaseActivationCount(); // Triggers fluent_cart_sl/license_limit_increased
415
+ $license->decreaseActivationCount(); // Triggers fluent_cart_sl/license_limit_decreased
416
+ $license->increaseLimit(10); // Sets limit to 10 or 'unlimited'
417
+ $license->regenerateKey(); // Generates new key UUID
418
+ $license->extendValidity('2026-12-31'); // Extends validity or passes 'lifetime'
419
+ $license->recountActivations(); // Recounts active sites
420
+ $downloads = $license->getDownloads(); // Gets downloadable files attached to license
421
+ ```
422
+
423
+ ---
424
+
425
+ ### `LicenseMeta` (`\FluentCartPro\App\Modules\Licensing\Models\LicenseMeta`)
426
+ * **Database Table:** `{wp_db_prefix}_fct_license_meta`
427
+ * **Source File:** `fluent-cart-pro/app/Modules/Licensing/Models/LicenseMeta.php`
428
+ * **Plugin:** FluentCart Pro
429
+
430
+ | Attribute | Type | Description |
431
+ |---|---|---|
432
+ | `id` | Integer | Primary key ID (guarded) |
433
+ | `object_id` | Integer | Reference to parent object ID (license ID, site ID, etc.) |
434
+ | `object_type` | String | Type slug of parent object (`license`, `activation`, `site`) |
435
+ | `meta_key` | String | Meta key name |
436
+ | `meta_value` | Text / JSON | Meta value (auto JSON encoded/decoded for arrays/objects) |
437
+
438
+ ```php
439
+ // Create polymorphic license meta entry
440
+ $meta = \FluentCartPro\App\Modules\Licensing\Models\LicenseMeta::create([
441
+ 'object_id' => 101,
442
+ 'object_type' => 'license',
443
+ 'meta_key' => 'renewal_info',
444
+ 'meta_value' => ['auto_renew' => true, 'next_date' => '2026-12-31']
445
+ ]);
446
+
447
+ // Pluck metadata key-value map for a license
448
+ $metaMap = \FluentCartPro\App\Modules\Licensing\Models\LicenseMeta::where('object_id', 101)
449
+ ->where('object_type', 'license')
450
+ ->pluck('meta_value', 'meta_key')
451
+ ->toArray();
452
+ ```
453
+
454
+ ---
455
+
456
+ ### `LicenseActivation` (`\FluentCartPro\App\Modules\Licensing\Models\LicenseActivation`)
457
+ * **Database Table:** `{wp_db_prefix}_fct_license_activations`
458
+ * **Source File:** `fluent-cart-pro/app/Modules/Licensing/Models/LicenseActivation.php`
459
+ * **Plugin:** FluentCart Pro
460
+
461
+ | Attribute | Type | Description |
462
+ |---|---|---|
463
+ | `id` | Integer | Primary key ID (guarded) |
464
+ | `site_id` | Integer | Foreign key to `fct_license_sites` |
465
+ | `license_id` | Integer | Foreign key to `fct_licenses` |
466
+ | `status` | String | Activation status slug (`active`, `inactive`) |
467
+ | `is_local` | Boolean | Whether site is local dev environment |
468
+ | `product_id` | Integer | Product ID |
469
+ | `variation_id` | Integer | Variation ID |
470
+ | `last_update_date` | DateTime | Timestamp of last software update check |
471
+ | `last_update_version` | String | Version string of last software update |
472
+ | `activation_method` | String | Method slug (e.g. `api`, `key_based`) |
473
+ | `activation_hash` | String | Unique activation security hash |
474
+
475
+ ```php
476
+ // Find activation record by ID
477
+ $activation = \FluentCartPro\App\Modules\Licensing\Models\LicenseActivation::find(1);
478
+
479
+ // Update status and trigger action hooks (fluent_cart_sl/license_activation_status_updated)
480
+ $activation->updateStatus('active');
481
+
482
+ // Access belongsTo relationships
483
+ $license = $activation->license;
484
+ $site = $activation->site;
485
+ ```
486
+
487
+ ---
488
+
489
+ ### `LicenseSite` (`\FluentCartPro\App\Modules\Licensing\Models\LicenseSite`)
490
+ * **Database Table:** `{wp_db_prefix}_fct_license_sites`
491
+ * **Source File:** `fluent-cart-pro/app/Modules/Licensing/Models/LicenseSite.php`
492
+ * **Plugin:** FluentCart Pro
493
+
494
+ | Attribute | Type | Description |
495
+ |---|---|---|
496
+ | `id` | Integer | Primary key ID (guarded) |
497
+ | `site_url` | String | Licensed website domain URL |
498
+ | `server_version` | String | Server environment string (e.g. `PHP 8.2`) |
499
+ | `platform_version` | String | Platform version (e.g. `WordPress 6.4`) |
500
+ | `other` | JSON | Additional server metadata array (auto encoded/decoded) |
501
+
502
+ ```php
503
+ // Check if site is local development domain (.test, .local, localhost, staging, dev)
504
+ $site = \FluentCartPro\App\Modules\Licensing\Models\LicenseSite::find(1);
505
+ if ($site->isLocalSite()) {
506
+ // Local development site logic
507
+ }
508
+
509
+ // Access attached activations hasMany relationship
510
+ $activations = $site->activations;
511
+ ```
512
+
513
+ ---
514
+
515
+ ### `OrderPromotion` (`\FluentCartPro\App\Modules\Promotional\Models\OrderPromotion`)
516
+ * **Database Table:** `{wp_db_prefix}_fct_order_promotions`
517
+ * **Source File:** `fluent-cart-pro/app/Modules/Promotional/Models/OrderPromotion.php`
518
+ * **Plugin:** FluentCart Pro
519
+
520
+ | Attribute | Type | Description |
521
+ |---|---|---|
522
+ | `id` | Integer | Primary key ID (guarded) |
523
+ | `hash` | String | Unique promotion hash (auto-generated on creation via md5) |
524
+ | `parent_id` | Integer | Parent promotion ID |
525
+ | `type` | String | Promotion type (`order_bump`, `upsell`) |
526
+ | `status` | String | Status (`draft`, `active`, `inactive`) |
527
+ | `src_object_id` | Integer | Source object ID |
528
+ | `src_object_type` | String | Source object type (`product_variation`) |
529
+ | `title` | String | Promotion title |
530
+ | `description` | Text | Promotion description |
531
+ | `conditions` | JSON | Conditions array (auto JSON encoded/decoded) |
532
+ | `config` | JSON | Configuration options array (auto JSON encoded/decoded) |
533
+ | `priority` | Integer | Priority order |
534
+
535
+ ```php
536
+ // Create active order bump promotion
537
+ $promotion = \FluentCartPro\App\Modules\Promotional\Models\OrderPromotion::create([
538
+ 'type' => 'order_bump',
539
+ 'status' => 'active',
540
+ 'src_object_id' => 123,
541
+ 'src_object_type' => 'product_variation',
542
+ 'title' => 'Special Add-on Offer',
543
+ 'conditions' => ['min_amount' => 5000, 'product_ids' => [1, 2]], // $50 min amount
544
+ 'config' => ['discount_type' => 'percentage', 'discount_value' => 15],
545
+ 'priority' => 1
546
+ ]);
547
+
548
+ // Access belongsTo product variant
549
+ $variant = $promotion->product_variant;
550
+ ```
551
+
552
+ ---
553
+
554
+ ### `OrderPromotionStat` (`\FluentCartPro\App\Modules\Promotional\Models\OrderPromotionStat`)
555
+ * **Database Table:** `{wp_db_prefix}_fct_order_promotion_stats`
556
+ * **Source File:** `fluent-cart-pro/app/Modules/Promotional/Models/OrderPromotionStat.php`
557
+ * **Plugin:** FluentCart Pro
558
+
559
+ | Attribute | Type | Description |
560
+ |---|---|---|
561
+ | `id` | Integer | Primary key ID (guarded) |
562
+ | `promotion_id` | Integer | Foreign key to `fct_order_promotions` |
563
+ | `order_id` | Integer | Foreign key to `fct_orders` |
564
+ | `object_id` | Integer | Related product or variation ID |
565
+ | `amount` | Decimal | Promotion revenue amount |
566
+ | `status` | String | Stat status (`offered`, `applied`, `declined`) |
567
+
568
+ ```php
569
+ // Track applied order bump promotion statistic
570
+ $stat = \FluentCartPro\App\Modules\Promotional\Models\OrderPromotionStat::create([
571
+ 'promotion_id' => 1,
572
+ 'order_id' => 501,
573
+ 'object_id' => 123,
574
+ 'amount' => 15.99,
575
+ 'status' => 'applied'
576
+ ]);
577
+
578
+ // Query stats with eager loaded order and promotion
579
+ $stats = \FluentCartPro\App\Modules\Promotional\Models\OrderPromotionStat::with(['order', 'promotion'])->get();
580
+ ```
581
+
582
+ ---
583
+
584
+ ### `UserMeta` (`\FluentCartPro\App\Models\UserMeta`)
585
+ * **Database Table:** `{wp_db_prefix}_usermeta`
586
+ * **Source File:** `fluent-cart-pro/app/Models/UserMeta.php`
587
+ * **Plugin:** FluentCart Pro
588
+
589
+ | Attribute | Type | Description |
590
+ |---|---|---|
591
+ | `umeta_id` | Integer | Primary Key ID |
592
+ | `user_id` | Integer | Foreign key to WordPress `users` table ID |
593
+ | `meta_key` | String | Meta key name |
594
+ | `meta_value` | Text | Meta value string or serialized data |
595
+
596
+ ```php
597
+ // Retrieve WordPress user meta entry
598
+ $userMeta = \FluentCartPro\App\Models\UserMeta::where('user_id', 42)
599
+ ->where('meta_key', 'fluent_cart_admin_role')
600
+ ->first();
601
+
602
+ // Access belongsTo WordPress User model relationship
603
+ $user = $userMeta->user;
604
+ ```