Skip to content
This repository was archived by the owner on May 21, 2025. It is now read-only.

Commit 0345354

Browse files
vbelolapotkovvbelolapotkov
committed
Generate initial docs based on the codebase
1 parent d48fb25 commit 0345354

File tree

4 files changed

+1021
-0
lines changed

4 files changed

+1021
-0
lines changed

‎docs/init.md

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# WooCommerce Subscriptions Core Initialization Sequence
2+
3+
This document explains how WooCommerce Subscriptions Core is loaded and initialized under different contexts including admin pages, customer-facing pages, Action Scheduler events, REST API requests, and AJAX calls.
4+
5+
## Core Initialization Flow
6+
7+
Regardless of the context, WooCommerce Subscriptions Core follows this base initialization sequence:
8+
9+
1. The main plugin class `WC_Subscriptions_Core_Plugin` is instantiated
10+
2. The autoloader is set up to handle class loading
11+
3. Constants are defined via `define_constants()`
12+
4. Required files are included via `includes()`
13+
5. Core components are initialized via `init()`
14+
6. Hooks are registered via `init_hooks()`
15+
16+
### Key Components Initialized
17+
18+
During the `init()` method, the following core components are initialized:
19+
20+
```php
21+
// Key classes initialized immediately
22+
WC_Subscriptions_Coupon::init();
23+
WC_Subscriptions_Product::init();
24+
WC_Subscriptions_Admin::init();
25+
WC_Subscriptions_Manager::init();
26+
WC_Subscriptions_Cart::init();
27+
WC_Subscriptions_Cart_Validator::init();
28+
WC_Subscriptions_Order::init();
29+
WC_Subscriptions_Renewal_Order::init();
30+
WC_Subscriptions_Checkout::init();
31+
WC_Subscriptions_Email::init();
32+
WC_Subscriptions_Email_Notifications::init();
33+
WC_Subscriptions_Addresses::init();
34+
WC_Subscriptions_Change_Payment_Gateway::init();
35+
$payment_gateways_handler::init();
36+
// ... and more core components
37+
38+
// Cart handlers are instantiated and stored
39+
$this->add_cart_handler(new WCS_Cart_Renewal());
40+
$this->add_cart_handler(new WCS_Cart_Resubscribe());
41+
$this->add_cart_handler(new WCS_Cart_Initial_Payment());
42+
43+
// Some classes are initialized later in the request lifecycle
44+
add_action('init', array('WC_Subscriptions_Synchroniser', 'init'));
45+
add_action('after_setup_theme', array('WC_Subscriptions_Upgrader', 'init'), 11);
46+
add_action('init', array('WC_PayPal_Standard_Subscriptions', 'init'), 11);
47+
```
48+
49+
### Hooks Registration
50+
51+
The `init_hooks()` method sets up the following key hooks:
52+
53+
1. Registration of custom order types and statuses
54+
2. Loading of translations
55+
3. Adding plugin action links
56+
4. Activation/deactivation procedures
57+
5. Action Scheduler batch size configuration
58+
6. Initialization of notification batch processor
59+
60+
## Context-Specific Initialization
61+
62+
### Admin Pages
63+
64+
When WooCommerce Subscriptions Core is loaded in the WordPress admin:
65+
66+
1. The core initialization flow runs first
67+
2. `WC_Subscriptions_Admin::init()` is called, which:
68+
- Loads admin-specific scripts and styles
69+
- Registers admin menus and settings
70+
- Sets up meta boxes for subscription editing
71+
- Configures admin notices
72+
73+
3. Version-dependent admin classes are initialized via `init_version_dependant_classes()`:
74+
```php
75+
new WCS_Admin_Post_Types();
76+
new WCS_Admin_Meta_Boxes();
77+
// ... other admin-specific components
78+
```
79+
80+
4. Admin-specific hooks are registered for:
81+
- Order management screens
82+
- Product management screens
83+
- Payment gateway configuration
84+
- Reporting and analytics
85+
86+
### Customer-Facing Pages
87+
88+
For front-end pages visible to customers:
89+
90+
1. The core initialization flow runs
91+
2. Front-end specific components are initialized:
92+
- `WC_Subscriptions_Cart` - manages subscription products in the cart
93+
- `WC_Subscriptions_Checkout` - handles checkout flow for subscriptions
94+
- `WC_Subscriptions_Frontend_Scripts` - loads necessary JS/CSS
95+
96+
3. No admin-specific components are loaded, which keeps front-end pages lean
97+
4. `WCS_Template_Loader` manages template overrides and customizations
98+
99+
### Action Scheduler Events
100+
101+
When an Action Scheduler event runs for subscriptions:
102+
103+
1. WordPress core loads and the request is identified as a `cron` request (Action Scheduler uses WP Cron)
104+
2. The core initialization flow runs, but admin UI components are not loaded
105+
3. `WCS_Action_Scheduler` (initialized during core initialization) processes the scheduled event:
106+
- Retrieves the correct subscription by ID from the action arguments
107+
- Performs the scheduled action (payment processing, trial end, etc.)
108+
- Updates subscription dates and statuses as appropriate
109+
110+
4. The subscription status may change based on the event, which then triggers:
111+
- Email notifications
112+
- Payment processing
113+
- Status changes and associated actions
114+
115+
### REST API Requests
116+
117+
For REST API requests related to subscriptions:
118+
119+
1. WordPress identifies the request as a REST API request via `WC()->is_rest_api_request()`
120+
2. The core initialization flow runs
121+
3. WC Subscriptions checks if it's a REST API request using `wcs_is_rest_api_request()`
122+
4. Admin UI components are not loaded to keep the request lightweight
123+
5. Data handling remains consistent with standard requests, but presentation layers are skipped
124+
125+
### AJAX Requests
126+
127+
For AJAX requests related to subscriptions:
128+
129+
1. WordPress identifies the request as an AJAX request via `wp_doing_ajax()`
130+
2. The core initialization flow runs
131+
3. WC Subscriptions checks if it's an AJAX request using `wcs_doing_ajax()`
132+
4. Depending on the specific AJAX action:
133+
- Admin-specific components may be loaded for admin AJAX requests
134+
- Front-end components for customer AJAX requests
135+
- The response is typically JSON formatted data rather than rendered HTML
136+
137+
## Key Differences Between Contexts
138+
139+
| Context | Admin UI Components | Frontend Components | Template Loading | Performance Considerations |
140+
|---------|--------------------|--------------------|-----------------|---------------------------|
141+
| Admin Pages | ✅ All loaded | ❌ Not loaded | ✅ Admin templates only | Loads more components for full functionality |
142+
| Customer Pages | ❌ Not loaded | ✅ All loaded | ✅ Frontend templates | Focuses on cart, checkout, and my-account functionality |
143+
| Action Scheduler | ❌ Not loaded | ❌ Not loaded | ❌ Not needed | Lightweight, focuses on data processing only |
144+
| REST API | ❌ Not loaded | ⚠️ Partial loading | ❌ Not needed | Data-focused, returns structured data |
145+
| AJAX | ⚠️ Context-dependent | ⚠️ Context-dependent | ❌ Not needed | Minimal loading for fast responses |
146+
147+
## Initialization Detection Functions
148+
149+
WC Subscriptions provides helper functions to determine the current request context:
150+
151+
```php
152+
// Check if current request is AJAX
153+
wcs_doing_ajax()
154+
155+
// Check if current request is wp-cron (includes Action Scheduler)
156+
wcs_doing_cron()
157+
158+
// Check if current request is REST API
159+
wcs_is_rest_api_request()
160+
161+
// Check if current request is frontend (not admin, not AJAX, not cron, not REST)
162+
wcs_is_frontend_request()
163+
```
164+
165+
## Performance Considerations
166+
167+
- Admin pages load the most components and have the highest overhead
168+
- Action Scheduler events are optimized for performance with minimal component loading
169+
- REST API and AJAX requests are designed to be lightweight for responsiveness
170+
- Frontend pages load only what's needed for customer interactions
171+
172+
## Common Issues and Troubleshooting
173+
174+
1. **Action Scheduler Events Not Running**: Check if cron is working correctly on your server and that the action is properly scheduled in the Action Scheduler tables.
175+
176+
2. **Admin vs Frontend Loading Conflicts**: If you're building a custom integration, be aware that some components aren't available in all contexts.
177+
178+
3. **REST API Authentication**: REST API requests require proper authentication; errors often occur due to permission issues rather than initialization problems.
179+
180+
4. **AJAX Nonce Verification**: AJAX requests include nonce verification that can fail if the user session expires.
181+
182+
## Extending the Initialization Process
183+
184+
To extend WooCommerce Subscriptions initialization, you can:
185+
186+
1. Hook into the appropriate WordPress or WooCommerce action hooks
187+
2. Use the plugin-specific filters provided by WC Subscriptions
188+
3. Implement your initialization logic in the correct context (admin, frontend, etc.)
189+
190+
Example:
191+
192+
```php
193+
// Add custom admin initialization
194+
add_action('woocommerce_subscriptions_initialized', function() {
195+
if (is_admin() && !wcs_doing_ajax()) {
196+
// Admin-specific initialization
197+
} elseif (wcs_is_frontend_request()) {
198+
// Frontend-specific initialization
199+
}
200+
});
201+
```

‎docs/overview.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# WooCommerce Subscriptions Core Overview
2+
3+
This document provides an overview of the WooCommerce Subscriptions Core codebase, designed to help developers understand the architecture, key components, and flows.
4+
5+
## Introduction
6+
7+
WooCommerce Subscriptions Core is a library that provides subscription functionality for WooCommerce. It allows store owners to sell products with recurring payments, handling the full subscription lifecycle including creation, renewals, cancellations, and more.
8+
9+
## Architecture
10+
11+
The codebase follows a modular, object-oriented architecture that integrates with WooCommerce. Here's the high-level structure:
12+
13+
1. **Core Subscription Object**: `WC_Subscription` extends `WC_Order` and represents a subscription with all its properties and methods.
14+
15+
2. **Main Plugin Class**: `WC_Subscriptions_Core_Plugin` handles initialization, hooks, and manages the plugin's lifecycle.
16+
17+
3. **Functional Organization**: Most functionality is organized into classes by feature with supporting functions in dedicated files.
18+
19+
## Key Components
20+
21+
### 1. Subscription Data Model
22+
23+
- `WC_Subscription` - Core class that represents a subscription
24+
- `WC_Subscriptions_Order` - Manages the relationship between orders and subscriptions
25+
- Data is stored in the `wp_posts` table as a custom `shop_subscription` post type with meta data in `wp_postmeta`
26+
27+
### 2. Product Types
28+
29+
- `WC_Product_Subscription` - Simple subscription product
30+
- `WC_Product_Variable_Subscription` - Variable subscription product
31+
- `WC_Product_Subscription_Variation` - Variation of a variable subscription
32+
33+
### 3. Cart and Checkout Handling
34+
35+
- `WC_Subscriptions_Cart` - Manages subscription products in the cart
36+
- `WC_Subscriptions_Checkout` - Handles the checkout process for subscriptions
37+
- Special cart handlers for different scenarios: renewals, resubscribes, switches, etc.
38+
39+
### 4. Payment Processing
40+
41+
- `WC_Subscriptions_Payment_Gateways` - Manages supported payment gateways
42+
- `WC_Subscriptions_Change_Payment_Gateway` - Handles payment method changes
43+
- Has integrations with specific gateways (e.g., PayPal)
44+
45+
### 5. Subscription Management
46+
47+
- `WC_Subscriptions_Manager` - Core management functionality
48+
- Handles activation, suspension, cancellation, etc.
49+
- Date calculation and management is a significant part
50+
51+
### 6. Admin Interface
52+
53+
- Various classes in the `admin/` directory handle the admin UI
54+
- Adds meta boxes, settings pages, list tables, etc.
55+
56+
### 7. Scheduling and Renewals
57+
58+
- `WCS_Action_Scheduler` - Handles scheduling of subscription events
59+
- `WC_Subscriptions_Renewal_Order` - Manages renewal orders
60+
- Uses WordPress's Action Scheduler for handling future events
61+
62+
## Key Flows and Entry Points
63+
64+
### 1. Subscription Creation
65+
66+
Flow typically starts when a customer purchases a subscription product:
67+
1. Customer adds a subscription product to cart
68+
2. Checkout process creates a parent order
69+
3. After payment, a subscription is created via `wcs_create_subscription()`
70+
4. Subscription is populated with data from the order
71+
72+
### 2. Subscription Renewals
73+
74+
1. Scheduled via Action Scheduler
75+
2. When the renewal date arrives, `WC_Subscriptions_Renewal_Order` creates a renewal order
76+
3. Payment is processed automatically for the renewal order
77+
4. On success, dates are updated for the next renewal
78+
79+
### 3. Status Changes
80+
81+
Subscriptions can have various statuses:
82+
- active: Currently active subscription
83+
- on-hold: Temporarily suspended
84+
- cancelled: Cancelled by customer or admin
85+
- expired: Reached its end date
86+
- pending-cancel: Will be cancelled at the end of the billing period
87+
88+
Status changes trigger actions that update dates, send emails, etc.
89+
90+
### 4. Customer-Initiated Actions
91+
92+
Customers can:
93+
- Cancel subscriptions
94+
- Change payment methods
95+
- Update subscription items (if allowed)
96+
- Pause/resume subscriptions (if enabled)
97+
98+
## Integration with WooCommerce
99+
100+
- Extends WooCommerce's product types, order system, and admin
101+
- Uses WooCommerce templates and overrides them when needed
102+
- Hooks into WooCommerce actions and filters to modify behavior
103+
104+
## Important Entry Points for New Features
105+
106+
1. `wcs-functions.php` - Core functions for working with subscriptions
107+
2. `WC_Subscriptions_Core_Plugin::init()` - Main initialization
108+
3. `WC_Subscription` class - Core subscription object with main methods
109+
4. Action hooks that are triggered on subscription events
110+
111+
## Key Files and Their Purpose
112+
113+
- `woocommerce-subscriptions-core.php` - Main plugin file with plugin information
114+
- `wcs-functions.php` - Core helper functions for working with subscriptions
115+
- `includes/class-wc-subscriptions-core-plugin.php` - Main plugin class that initializes everything
116+
- `includes/class-wc-subscription.php` - Core subscription object model
117+
- `includes/class-wc-subscriptions-order.php` - Manages the relationship between orders and subscriptions
118+
- `includes/class-wc-subscriptions-manager.php` - Handles overall subscription management
119+
- `includes/class-wc-subscriptions-cart.php` - Manages subscriptions in the cart
120+
- `includes/class-wc-subscriptions-checkout.php` - Handles checkout process for subscriptions
121+
122+
## Directory Structure
123+
124+
- `/includes/` - Main PHP classes for the plugin
125+
- `/admin/` - Admin-specific functionality
126+
- `/gateways/` - Payment gateway integrations
127+
- `/emails/` - Email notifications
128+
- `/data-stores/` - Custom data store implementations
129+
- `/templates/` - Template files for frontend display
130+
- `/assets/` - JavaScript, CSS, and image files
131+
- `/languages/` - Translation files
132+
133+
## Hooks and Extension Points
134+
135+
The plugin provides numerous action and filter hooks for extending its functionality. Some important ones include:
136+
137+
- `woocommerce_subscription_status_updated`
138+
- `woocommerce_subscription_payment_complete`
139+
- `woocommerce_subscription_renewal_payment_failed`
140+
- `woocommerce_subscription_date_updated`

0 commit comments

Comments
 (0)