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,154 @@
|
|
|
1
|
+
# FluentCart Core Complete Developer Guide
|
|
2
|
+
|
|
3
|
+
> Source: Official FluentCart Developer Guide Documentation
|
|
4
|
+
|
|
5
|
+
Welcome to the complete developer guide for **FluentCart** — the self-hosted e-commerce plugin for WordPress. This guide covers core principles, architecture, extension points, codebase structure, and quick start instructions for developing custom add-ons, modules, and integrations.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 🚀 Overview
|
|
10
|
+
|
|
11
|
+
### What is FluentCart?
|
|
12
|
+
FluentCart is a **Self-Hosted E-commerce Plugin for WordPress** that helps businesses manage online stores, process payments, handle orders, and manage customers natively inside WordPress.
|
|
13
|
+
|
|
14
|
+
Unlike cloud-based SaaS solutions, FluentCart runs entirely on your WordPress site, ensuring total data privacy, unlimited products, zero order transaction surcharges, and complete operational control.
|
|
15
|
+
|
|
16
|
+
### Why Extend FluentCart?
|
|
17
|
+
FluentCart is engineered from the ground up for deep extensibility:
|
|
18
|
+
|
|
19
|
+
- **315+ Action and Filter Hooks** for intercepting and customizing core execution flows.
|
|
20
|
+
- **Modular Architecture** allowing clean separation of payment gateways, shipping methods, and custom modules.
|
|
21
|
+
- **RESTful API** offering complete programmatic access to e-commerce resources.
|
|
22
|
+
- **WordPress-Native Standards** following modern PHP, PSR coding standards, and WordPress conventions.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 📦 FluentCart Core vs. Pro Version Comparison
|
|
27
|
+
|
|
28
|
+
| Feature Category | Core (Free Version) | Pro (Premium Version) |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| **Product & Catalog** | Unlimited products, simple & variable pricing | Advanced variations & ghost products |
|
|
31
|
+
| **Order Processing** | Complete order management & receipts | Automated post-order workflows & order operation logs |
|
|
32
|
+
| **Customer Management** | Customer profiles, LTV tracking & addresses | Custom customer meta, advanced segmentation |
|
|
33
|
+
| **Payments & Shipping** | Core payment gateways & shipping zones | Dynamic shipping carriers, custom payment integrations |
|
|
34
|
+
| **Coupons & Discounts** | Standard discount codes & conditions | Stackable coupons, auto-applied promos & Order Bumps |
|
|
35
|
+
| **Software Licensing** | N/A | Full software license keys, site activations & updates |
|
|
36
|
+
| **Subscriptions** | N/A | Recurring billing cycles, trial periods & grace periods |
|
|
37
|
+
| **Roles & Permissions** | Basic WordPress capability checks | Granular team roles & permission management |
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🏗 Core Development Concepts
|
|
42
|
+
|
|
43
|
+
### 1. Data Architecture
|
|
44
|
+
FluentCart uses a clean, normalized database structure with integer monetary values stored in **cents**:
|
|
45
|
+
|
|
46
|
+
- **Orders (`fct_orders`):** Central record for order status, customer links, totals, and payment status.
|
|
47
|
+
- **Customers (`fct_customers`):** Profiles linked to WordPress users or guest transactions.
|
|
48
|
+
- **Products (WordPress Posts):** Core product metadata stored as custom post types, supplemented by `fct_product_details` and `fct_product_variations`.
|
|
49
|
+
- **Transactions (`fct_order_transactions`):** Payment charges, refunds, and gateway interaction records.
|
|
50
|
+
- **Subscriptions (`fct_subscriptions`):** Recurring billing metadata, billing cycles, and next billing schedules.
|
|
51
|
+
|
|
52
|
+
### 2. Extension Points
|
|
53
|
+
- **WordPress Action Hooks:** Execute custom code on events (e.g. `fluent_cart/order_paid_done`).
|
|
54
|
+
- **WordPress Filter Hooks:** Modify data in-flight (e.g. `fluent_cart/fee_items`).
|
|
55
|
+
- **Module System:** Register custom payment gateways, shipping carriers, and storage drivers.
|
|
56
|
+
- **REST API:** Build external applications, dashboards, or headless checkout experiences.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 📁 Application Codebase Directory Structure
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
fluent-cart/
|
|
64
|
+
├── app/ # Core application logic
|
|
65
|
+
│ ├── Hooks/ # WordPress action/filter handlers
|
|
66
|
+
│ │ ├── Handlers/ # Action/Filter handler classes
|
|
67
|
+
│ │ ├── actions.php # Action hook definitions
|
|
68
|
+
│ │ └── filters.php # Filter hook definitions
|
|
69
|
+
│ ├── Http/ # HTTP layer
|
|
70
|
+
│ │ ├── Controllers/ # Admin & REST API controllers
|
|
71
|
+
│ │ ├── Middleware/ # Request authentication & authorization
|
|
72
|
+
│ │ └── Routes/ # API and admin route definitions
|
|
73
|
+
│ ├── Models/ # Eloquent ORM database models (45+ models)
|
|
74
|
+
│ │ ├── Order.php # Order model
|
|
75
|
+
│ │ ├── Customer.php # Customer model
|
|
76
|
+
│ │ ├── Product.php # Product model
|
|
77
|
+
│ │ └── ... # Core & Pro model files
|
|
78
|
+
│ ├── Services/ # Core business logic services
|
|
79
|
+
│ │ ├── Payment/ # Payment processing drivers
|
|
80
|
+
│ │ ├── Shipping/ # Shipping calculation engines
|
|
81
|
+
│ │ └── Helper.php # Global helper utility functions
|
|
82
|
+
│ ├── Views/ # Admin PHP template views
|
|
83
|
+
│ ├── Events/ # Internal application events
|
|
84
|
+
│ ├── Listeners/ # Event listeners
|
|
85
|
+
│ └── Modules/ # Module registration system
|
|
86
|
+
│
|
|
87
|
+
├── api/ # REST API resources & endpoint controllers
|
|
88
|
+
│ ├── Orders.php # Order management REST endpoints
|
|
89
|
+
│ ├── Customers.php # Customer management REST endpoints
|
|
90
|
+
│ ├── Products.php # Product catalog REST endpoints
|
|
91
|
+
│ └── Resource/ # JSON response resource transformers
|
|
92
|
+
│
|
|
93
|
+
├── resources/ # Frontend application assets
|
|
94
|
+
│ ├── admin/ # Vue.js admin single-page application & Gutenberg blocks
|
|
95
|
+
│ ├── public/ # Storefront cart, checkout & portal components
|
|
96
|
+
│ └── styles/ # Core SCSS/CSS design tokens
|
|
97
|
+
│
|
|
98
|
+
├── database/ # Database schema migrations & seeders
|
|
99
|
+
│ ├── Migrations/ # Table migration files (34+ migrations)
|
|
100
|
+
│ └── DBMigrator.php # Database migration manager
|
|
101
|
+
│
|
|
102
|
+
└── fluent-cart.php # Main WordPress plugin bootstrap entry file
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## ⚡ Quick Start Extension Blueprints
|
|
108
|
+
|
|
109
|
+
### 1. Registering a Custom Extension
|
|
110
|
+
```php
|
|
111
|
+
<?php
|
|
112
|
+
/**
|
|
113
|
+
* Plugin Name: FluentCart Custom Extension
|
|
114
|
+
* Description: Extension module for FluentCart e-commerce.
|
|
115
|
+
* Version: 1.0.0
|
|
116
|
+
* Author: Developer
|
|
117
|
+
*/
|
|
118
|
+
|
|
119
|
+
if (!defined('ABSPATH')) {
|
|
120
|
+
exit; // Prevent direct execution access
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// Attach listener to WordPress plugins_loaded hook
|
|
124
|
+
add_action('plugins_loaded', function () {
|
|
125
|
+
// Verify that FluentCart plugin is active
|
|
126
|
+
if (!defined('FLUENT_CART')) {
|
|
127
|
+
return; // Exit early if FluentCart is missing
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// Initialize custom hook listeners and extension modules here
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### 2. Post-Payment Asynchronous Task Listener
|
|
135
|
+
```php
|
|
136
|
+
// Intercept order paid event asynchronously via Action Scheduler
|
|
137
|
+
add_action('fluent_cart/order_paid_done', function ($payload) {
|
|
138
|
+
// Extract Order model instance from payload array
|
|
139
|
+
$order = $payload['order'];
|
|
140
|
+
|
|
141
|
+
// Extract Customer model instance from payload array
|
|
142
|
+
$customer = $payload['customer'];
|
|
143
|
+
|
|
144
|
+
// Convert total order amount from integer cents to decimal format
|
|
145
|
+
$orderTotal = \FluentCart\App\Helpers\Helper::toDecimal($order->total_amount);
|
|
146
|
+
|
|
147
|
+
// Log payment details into FluentCart system activity log
|
|
148
|
+
fluent_cart_add_log(
|
|
149
|
+
'Order Completed',
|
|
150
|
+
"Order #{$order->id} for {$customer->email} completed. Amount: ${orderTotal}",
|
|
151
|
+
'info'
|
|
152
|
+
);
|
|
153
|
+
}, 10, 1);
|
|
154
|
+
```
|
|
@@ -0,0 +1,458 @@
|
|
|
1
|
+
# Ghost Product Selling Options
|
|
2
|
+
|
|
3
|
+
FluentCart provides a powerful hook system that allows developers to sell ghost products that don't exist in the product catalog. This feature enables selling add-ons, gift wrapping, custom subscriptions, and any other custom items through your store.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
Custom product selling allows you to add items to the cart that are not stored as regular products in the database. This is useful for:
|
|
10
|
+
|
|
11
|
+
- **Add-on Products** - Gift wrapping, insurance, custom options
|
|
12
|
+
- **Custom Subscriptions** - Recurring billing for non-catalog items
|
|
13
|
+
- **Dynamic Products** - Products created on-the-fly based on user selections
|
|
14
|
+
- **Service-Based Items** - One-time or recurring service purchases
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Implementation Flow
|
|
19
|
+
|
|
20
|
+
The complete implementation follows this flow:
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
Add Button → Add Validation Hook → Handle Quantity Change Hook → Checkout Validation Hook
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Step 1: Add Button (Frontend)
|
|
29
|
+
|
|
30
|
+
Add the appropriate button to your page based on the item type.
|
|
31
|
+
|
|
32
|
+
### One-Time Custom Item (Add to Cart)
|
|
33
|
+
|
|
34
|
+
For one-time purchases that are added to the cart:
|
|
35
|
+
|
|
36
|
+
```html
|
|
37
|
+
<button
|
|
38
|
+
data-cart-id="1000"
|
|
39
|
+
data-quantity="1"
|
|
40
|
+
data-is-custom="true"
|
|
41
|
+
data-fluent-cart-add-to-cart-button
|
|
42
|
+
>
|
|
43
|
+
Add Gift Wrapping
|
|
44
|
+
</button>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Subscription Custom Item (Instant Checkout)
|
|
48
|
+
|
|
49
|
+
For subscription items that go directly to checkout:
|
|
50
|
+
|
|
51
|
+
```html
|
|
52
|
+
<a href="https://yourstore.com/?fluent-cart=instant_checkout&item_id=3001&quantity=1&is_custom=true">
|
|
53
|
+
Buy Now
|
|
54
|
+
</a>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
> **Note:** Replace `https://yourstore.com` with your actual site URL and `3001` with your custom item ID.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Step 2: Add Validation Hook (Backend)
|
|
62
|
+
|
|
63
|
+
Use this filter to validate and return the custom product item when it's added to the cart.
|
|
64
|
+
|
|
65
|
+
### Hook: `fluent_cart/cart/validate_custom_item`
|
|
66
|
+
|
|
67
|
+
**Parameters:**
|
|
68
|
+
|
|
69
|
+
| Parameter | Type | Description |
|
|
70
|
+
|-----------|------|-------------|
|
|
71
|
+
| `$variation` | `object/array` | The variation object to be modified |
|
|
72
|
+
| `$item` | `array` | The item data from the request |
|
|
73
|
+
|
|
74
|
+
**Returns:** The modified variation object
|
|
75
|
+
|
|
76
|
+
### Example: Validate New Custom Item
|
|
77
|
+
|
|
78
|
+
```php
|
|
79
|
+
add_filter('fluent_cart/cart/validate_custom_item',
|
|
80
|
+
function($variation, $item) {
|
|
81
|
+
// Check if the item is flagged as custom
|
|
82
|
+
if ((bool)$item['is_custom']) {
|
|
83
|
+
// Build the custom variation object with all required fields
|
|
84
|
+
$variation = (object) [
|
|
85
|
+
'item_id' => absint($item['item_id']),
|
|
86
|
+
'object_id' => absint($item['item_id']),
|
|
87
|
+
'post_id' => 5000,
|
|
88
|
+
'quantity' => max(1, (int)$item['quantity']),
|
|
89
|
+
'price' => floatval(5000),
|
|
90
|
+
'unit_price' => floatval(5000),
|
|
91
|
+
'line_total' => floatval(5000) * max(1, (int)$item['quantity']),
|
|
92
|
+
'post_title' => sanitize_text_field('Weekly Protein Pack'),
|
|
93
|
+
'title' => sanitize_text_field('Subscription Version 1'),
|
|
94
|
+
'is_custom' => true,
|
|
95
|
+
'payment_type' => 'subscription',
|
|
96
|
+
"other_info" => [
|
|
97
|
+
"payment_type" => "subscription",
|
|
98
|
+
"repeat_interval" => "monthly",
|
|
99
|
+
"installment" => "no",
|
|
100
|
+
"manage_setup_fee" => "yes",
|
|
101
|
+
"signup_fee" => 500
|
|
102
|
+
],
|
|
103
|
+
|
|
104
|
+
];
|
|
105
|
+
}
|
|
106
|
+
return $variation;
|
|
107
|
+
}, 10, 2);
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Step 3: Handle Quantity Changes (Cart)
|
|
113
|
+
|
|
114
|
+
This step applies only to **one-time items** for quantity increment/decrement actions.
|
|
115
|
+
|
|
116
|
+
### Hook: `fluent_cart/cart/custom_item_quantity_changed`
|
|
117
|
+
|
|
118
|
+
**Parameters:**
|
|
119
|
+
|
|
120
|
+
| Parameter | Type | Description |
|
|
121
|
+
|-----------|------|-------------|
|
|
122
|
+
| `$variation` | `object/array` | The variation object to be updated |
|
|
123
|
+
| `$item` | `array` | Item data including quantity changes |
|
|
124
|
+
|
|
125
|
+
**Returns:** The modified variation object with updated quantity and totals
|
|
126
|
+
|
|
127
|
+
### Example: Change Existing Item Quantity
|
|
128
|
+
|
|
129
|
+
```php
|
|
130
|
+
add_filter('fluent_cart/cart/custom_item_quantity_changed', function ($variation, $item) {
|
|
131
|
+
|
|
132
|
+
// Skip non-custom items
|
|
133
|
+
if (empty($item['is_custom'])) {
|
|
134
|
+
return $variation;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// Ensure array format for manipulation
|
|
138
|
+
$variation = (array) $variation;
|
|
139
|
+
|
|
140
|
+
$newQty = (int) ($item['new_quantity'] ?? 1);
|
|
141
|
+
$oldQty = (int) ($item['old_quantity'] ?? 1);
|
|
142
|
+
$byInput = (bool) ($item['by_input'] ?? false);
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* If quantity changed via increment, decrement or delete buttons
|
|
146
|
+
*/
|
|
147
|
+
if (!$byInput) {
|
|
148
|
+
$newQty = $newQty == 0 ? 0 : ($oldQty+$newQty);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
// Recalculate line total based on new quantity
|
|
152
|
+
$price = (float) ($variation['price'] ?? 0);
|
|
153
|
+
|
|
154
|
+
$variation['quantity'] = $newQty;
|
|
155
|
+
$variation['line_total'] = $price * $newQty;
|
|
156
|
+
|
|
157
|
+
return $variation;
|
|
158
|
+
|
|
159
|
+
}, 10, 2);
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Step 4: Checkout Validation
|
|
165
|
+
|
|
166
|
+
This hook runs before payment processing for both one-time and subscription items.
|
|
167
|
+
|
|
168
|
+
### Hook: `fluent_cart/payment/validate_custom_item`
|
|
169
|
+
|
|
170
|
+
**Parameters:**
|
|
171
|
+
|
|
172
|
+
| Parameter | Type | Description |
|
|
173
|
+
|-----------|------|-------------|
|
|
174
|
+
| `$items` | `array` | Array containing product and variation objects |
|
|
175
|
+
| `$data` | `array` | Additional checkout data |
|
|
176
|
+
|
|
177
|
+
**Returns:** Modified items array
|
|
178
|
+
|
|
179
|
+
### Example: Payment Validate Item
|
|
180
|
+
|
|
181
|
+
```php
|
|
182
|
+
add_filter('fluent_cart/payment/validate_custom_item', function ($items, $data) {
|
|
183
|
+
|
|
184
|
+
[$product, $variation] = $items;
|
|
185
|
+
|
|
186
|
+
// Mark the item as custom visually in admin and receipts
|
|
187
|
+
$variation->title .= ' (Custom Item)';
|
|
188
|
+
$product->post_title .= ' [Custom]';
|
|
189
|
+
|
|
190
|
+
return [$product, $variation];
|
|
191
|
+
|
|
192
|
+
}, 10, 2);
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Step 5: Admin Order Update Handling (Optional)
|
|
198
|
+
|
|
199
|
+
Handle custom item updates from the WordPress admin panel after an order is placed.
|
|
200
|
+
|
|
201
|
+
### Order Item Changed
|
|
202
|
+
|
|
203
|
+
**Action:** `fluent_cart/order/custom_item_changed`
|
|
204
|
+
|
|
205
|
+
**Parameters:**
|
|
206
|
+
|
|
207
|
+
| Parameter | Type | Description |
|
|
208
|
+
|-----------|------|-------------|
|
|
209
|
+
| `$oldItem` | `array` | The original item data |
|
|
210
|
+
| `$item` | `array` | The updated item data |
|
|
211
|
+
|
|
212
|
+
**Returns:** The item to be saved
|
|
213
|
+
|
|
214
|
+
### Example: Order Item Changed
|
|
215
|
+
|
|
216
|
+
```php
|
|
217
|
+
add_filter('fluent_cart/order/custom_item_changed', function ($oldItem, $item) {
|
|
218
|
+
|
|
219
|
+
$oldItem = (array) $oldItem;
|
|
220
|
+
$item = (array) $item;
|
|
221
|
+
|
|
222
|
+
$isCustom = (bool) ($item['is_custom'] ?? false);
|
|
223
|
+
$newQuantity = (int) ($item['quantity'] ?? 1);
|
|
224
|
+
$oldQuantity = (int) ($oldItem['quantity'] ?? 1);
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* If item is a Custom Item → always save updated changes
|
|
228
|
+
*/
|
|
229
|
+
if ($isCustom) {
|
|
230
|
+
return $item;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* If quantity is unchanged → return old item (no update)
|
|
235
|
+
*/
|
|
236
|
+
if ($oldQuantity === $newQuantity) {
|
|
237
|
+
return $oldItem;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* If quantity changed → allow update
|
|
242
|
+
*/
|
|
243
|
+
return $item;
|
|
244
|
+
|
|
245
|
+
}, 10, 2);
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Before Custom Items Are Deleted
|
|
249
|
+
|
|
250
|
+
**Action:** `fluent_cart/order/before_custom_items_deleted`
|
|
251
|
+
|
|
252
|
+
**Parameters:**
|
|
253
|
+
|
|
254
|
+
| Parameter | Type | Description |
|
|
255
|
+
|-----------|------|-------------|
|
|
256
|
+
| `$customItems` | `array` | Array of custom items to be deleted |
|
|
257
|
+
| `$order` | `object` | The order object |
|
|
258
|
+
|
|
259
|
+
### Example: Before Order Item Deleted
|
|
260
|
+
|
|
261
|
+
```php
|
|
262
|
+
add_action('fluent_cart/order/before_custom_items_deleted', function ($customItems, $order) {
|
|
263
|
+
|
|
264
|
+
// Log each custom item before deletion
|
|
265
|
+
foreach ($customItems as $item) {
|
|
266
|
+
error_log(
|
|
267
|
+
sprintf(
|
|
268
|
+
'Custom item about to be deleted. Order #%d | Item ID: %d | Qty: %d',
|
|
269
|
+
$order->id,
|
|
270
|
+
$item->id,
|
|
271
|
+
$item->quantity
|
|
272
|
+
)
|
|
273
|
+
);
|
|
274
|
+
|
|
275
|
+
// Restore external stock if needed
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
}, 10, 2);
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### After Custom Items Are Deleted
|
|
282
|
+
|
|
283
|
+
**Action:** `fluent_cart/order/after_custom_items_deleted`
|
|
284
|
+
|
|
285
|
+
**Parameters:**
|
|
286
|
+
|
|
287
|
+
| Parameter | Type | Description |
|
|
288
|
+
|-----------|------|-------------|
|
|
289
|
+
| `$customItems` | `array` | Array of deleted custom items |
|
|
290
|
+
| `$order` | `object` | The order object |
|
|
291
|
+
|
|
292
|
+
### Example: After Order Item Deleted
|
|
293
|
+
|
|
294
|
+
```php
|
|
295
|
+
add_action('fluent_cart/order/after_custom_items_deleted', function ($customItems, $order) {
|
|
296
|
+
|
|
297
|
+
// Log deletion and perform cleanup for each item
|
|
298
|
+
foreach ($customItems as $item) {
|
|
299
|
+
error_log(
|
|
300
|
+
sprintf(
|
|
301
|
+
'Custom item deleted. Order #%d | Item ID: %d | Qty: %d',
|
|
302
|
+
$order->id,
|
|
303
|
+
$item->id,
|
|
304
|
+
$item->quantity
|
|
305
|
+
)
|
|
306
|
+
);
|
|
307
|
+
|
|
308
|
+
// Analytics or internal counters
|
|
309
|
+
// Notify admin
|
|
310
|
+
// wp_mail('admin@example.com', 'Custom Item Deleted', 'Item ID ' . $item->id . ' was deleted');
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
}, 10, 2);
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Sample Datasets
|
|
319
|
+
|
|
320
|
+
### One-Time Item
|
|
321
|
+
|
|
322
|
+
```php
|
|
323
|
+
$item = [
|
|
324
|
+
"item_id" => 1000,
|
|
325
|
+
"object_id" => 1000,
|
|
326
|
+
"post_id" => 10000,
|
|
327
|
+
"quantity" => 1,
|
|
328
|
+
"is_custom" => true,
|
|
329
|
+
"post_title" => "Air Max 1 running shoe",
|
|
330
|
+
"title" => "Version 1",
|
|
331
|
+
"price" => 2000,
|
|
332
|
+
"unit_price" => 2000,
|
|
333
|
+
"line_total" => 2000 * 1, // quantity is 1
|
|
334
|
+
"payment_type" => "onetime",
|
|
335
|
+
"fulfillment_type" => "digital",
|
|
336
|
+
"featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/white-navy-athletic-shoe-4-1.jpeg",
|
|
337
|
+
"sold_individually"=> 0,
|
|
338
|
+
"other_info" => [
|
|
339
|
+
"payment_type" => "onetime"
|
|
340
|
+
],
|
|
341
|
+
"view_url" => "https://www.example.com/product/air-max-1-running-shoe"
|
|
342
|
+
];
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### Subscription Item
|
|
346
|
+
|
|
347
|
+
```php
|
|
348
|
+
$item = [
|
|
349
|
+
"item_id" => 2000,
|
|
350
|
+
"object_id" => 2000,
|
|
351
|
+
"post_id" => 20000,
|
|
352
|
+
"quantity" => 1, // always 1 for subscription
|
|
353
|
+
"is_custom" => true,
|
|
354
|
+
"post_title" => "Weekly Protein Pack",
|
|
355
|
+
"title" => "Subscription Version 1",
|
|
356
|
+
"price" => 2500,
|
|
357
|
+
"unit_price" => 2500,
|
|
358
|
+
"line_total" => 2500 * 1,
|
|
359
|
+
"payment_type" => "subscription",
|
|
360
|
+
"fulfillment_type" => "digital",
|
|
361
|
+
"featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/protein-pack-1.jpeg",
|
|
362
|
+
"sold_individually"=> 1, // enforce quantity = 1
|
|
363
|
+
"other_info" => [
|
|
364
|
+
"payment_type" => "subscription",
|
|
365
|
+
"repeat_interval" => "monthly",
|
|
366
|
+
"installment" => "no",
|
|
367
|
+
"manage_setup_fee" => "yes",
|
|
368
|
+
"signup_fee" => 500
|
|
369
|
+
],
|
|
370
|
+
"view_url" => "https://www.example.com/product/weekly-protein-pack"
|
|
371
|
+
];
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
### Payment Gateway Validation During Checkout
|
|
375
|
+
|
|
376
|
+
```php
|
|
377
|
+
$variation = (object)[
|
|
378
|
+
"item_id" => 1000,
|
|
379
|
+
"object_id" => 1000,
|
|
380
|
+
"post_id" => 10000,
|
|
381
|
+
"quantity" => 1,
|
|
382
|
+
"is_custom" => true,
|
|
383
|
+
"post_title" => "Air Max 1 running shoe",
|
|
384
|
+
"title" => "Version 1",
|
|
385
|
+
"price" => 2000,
|
|
386
|
+
"unit_price" => 2000,
|
|
387
|
+
"line_total" => 2000 * 1,
|
|
388
|
+
"payment_type" => "onetime",
|
|
389
|
+
"fulfillment_type" => "digital",
|
|
390
|
+
"featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/white-navy-athletic-shoe-4-1.jpeg",
|
|
391
|
+
"sold_individually"=> 0,
|
|
392
|
+
"other_info" => [
|
|
393
|
+
"payment_type" => "onetime"
|
|
394
|
+
],
|
|
395
|
+
"view_url" => "https://www.example.com/product/air-max-1-running-shoe"
|
|
396
|
+
];
|
|
397
|
+
|
|
398
|
+
$product = (object)[
|
|
399
|
+
"ID" => 148,
|
|
400
|
+
"post_title" => "Air Max 1 running shoe",
|
|
401
|
+
"post_status" => "publish",
|
|
402
|
+
];
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
---
|
|
406
|
+
|
|
407
|
+
## Key Properties Reference
|
|
408
|
+
|
|
409
|
+
### Item Object Properties
|
|
410
|
+
|
|
411
|
+
| Property | Type | Description | Example |
|
|
412
|
+
|----------|------|-------------|---------|
|
|
413
|
+
| `item_id` | integer | Unique identifier for the custom item | `1000` |
|
|
414
|
+
| `object_id` | integer | Reference ID for the item | `1000` |
|
|
415
|
+
| `post_id` | integer | WordPress post ID reference | `5000` |
|
|
416
|
+
| `quantity` | integer | Item quantity | `1` |
|
|
417
|
+
| `is_custom` | boolean | Marks item as custom | `true` |
|
|
418
|
+
| `post_title` | string | Product title | `"Air Max 1 running shoe"` |
|
|
419
|
+
| `title` | string | Variation title | `"Version 1"` |
|
|
420
|
+
| `price` | float | Unit price | `2000` |
|
|
421
|
+
| `unit_price` | float | Unit price (same as price) | `2000` |
|
|
422
|
+
| `line_total` | float | Total price (price × quantity) | `2000` |
|
|
423
|
+
| `payment_type` | string | `onetime` or `subscription` | `"onetime"` |
|
|
424
|
+
| `fulfillment_type` | string | `digital` or `physical` | `"digital"` |
|
|
425
|
+
| `featured_media` | string | Media URL | `"http://..."` |
|
|
426
|
+
| `sold_individually` | integer | `0` for no, `1` for yes | `0` |
|
|
427
|
+
| `other_info` | array | Additional information | See below |
|
|
428
|
+
|
|
429
|
+
### `other_info` Properties for Subscriptions
|
|
430
|
+
|
|
431
|
+
| Property | Type | Description | Example |
|
|
432
|
+
|----------|------|-------------|---------|
|
|
433
|
+
| `payment_type` | string | Type of payment | `"subscription"` |
|
|
434
|
+
| `repeat_interval` | string | Billing frequency | `"monthly"` |
|
|
435
|
+
| `installment` | string | Installment plan | `"no"` |
|
|
436
|
+
| `manage_setup_fee` | string | Enable setup fee | `"yes"` |
|
|
437
|
+
| `signup_fee` | float | Setup fee amount | `500` |
|
|
438
|
+
|
|
439
|
+
---
|
|
440
|
+
|
|
441
|
+
## Best Practices
|
|
442
|
+
|
|
443
|
+
- **Always Validate Data:** Use the validation hook to ensure item data is correct before adding to cart
|
|
444
|
+
- **Handle Quantity Changes:** Implement quantity change handlers for one-time items
|
|
445
|
+
- **Mark Custom Items:** Use `is_custom` flag to distinguish custom items from regular products (required for all custom items)
|
|
446
|
+
- **Set Correct Payment Type:** Ensure `payment_type` is set correctly (`onetime` or `subscription`)
|
|
447
|
+
- **Calculate Totals:** Always calculate `line_total` as `price × quantity`
|
|
448
|
+
- **Use Sanitization:** Apply `sanitize_text_field()` and `absint()` for security
|
|
449
|
+
- **Handle Admin Actions:** Implement order update handlers if admins will modify orders
|
|
450
|
+
|
|
451
|
+
---
|
|
452
|
+
|
|
453
|
+
## Related Documentation
|
|
454
|
+
|
|
455
|
+
- [Developer Hooks](action-hooks-orders.md) - Complete hooks and filters reference
|
|
456
|
+
- [Products API](rest-api-reference.md) - Product management API
|
|
457
|
+
- [Orders API](rest-api-reference.md) - Order management API
|
|
458
|
+
- [Database Models](database-models-reference.md) - Data model documentation
|