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.
- package/.gitattributes +2 -0
- package/CLAUDE.md +22 -0
- package/CONTRIBUTING.md +73 -0
- package/LICENSE +21 -0
- package/README.md +127 -0
- package/SKILL.md +127 -0
- package/bin/index.js +281 -0
- package/copy-skills.js +43 -0
- package/package.json +38 -0
- package/skills/fluentcart-developer/SKILL.md +172 -0
- package/skills/fluentcart-developer/examples/README.md +25 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
- package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
- package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
- package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
- package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
- package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
- package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
- package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
- package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
- package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
- package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
- package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
- package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
- package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
- package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
- package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
- package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
- package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
- package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
- package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
- package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
- package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
- package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
- package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
- package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
- package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
- package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
- package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
- package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
- package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
- package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
- package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
- package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
- package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
- package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
- package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
- package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
- package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
- package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
- package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
- package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
- package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
- package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
- package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
- package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
- package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
- package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
- package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
- package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
- package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
- package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
- package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
- package/skills/fluentcart-developer/scripts/cli.js +1 -0
- 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
|
+
```
|