TSJ Subscriptions Controller Documentation

Overview

The TSJ_Subscriptions_Controller class is a core controller that handles various subscription-related actions and events in the TSJ Subscriptions plugin. It integrates with WordPress and WooCommerce to manage subscription lifecycle events, updates, and maintenance tasks.

Class Definition 

class TSJ_Subscriptions_Controller {
    protected $expired_monthly_process;
}

Key Responsibilities

1. Subscription Lifecycle Management

  • Handles new subscription creation
  • Manages subscription renewals
  • Processes subscription updates and modifications
  • Handles subscription deletion

2. Payment Processing

  • Processes new subscription payments
  • Handles renewal payments
  • Manages payment completion events

3. Subscription Data Management

  • Updates subscription metadata
  • Manages subscription status changes
  • Handles address updates and key management
  • Processes SKU updates

4. Activity Tracking

The controller creates activity records for various subscription events:

  • Subscription creation
  • Subscription renewal
  • Subscription merging
  • Gift subscription conversion
  • Subscription editing
  • Auto-renewal
  • Pending renewal creation
  • Batch subscription shipping updates

Key Methods

1. new_subscription_payment_complete($subscription_id)

  • Handles initial subscription setup after payment completion
  • Sets up circulation management data
  • Configures start and expiry issues
  • Sets copies owed and other subscription parameters

2. update_subscription($subscription_id, $start_issue_id, $expiry_issue_id, $copies_owed, $deferred_amount, $notes, $notification_date, $benefactor_subscription, $shipping_basis)

  • Updates subscription details in circulation management
  • Modifies start and expiry issues
  • Updates copies owed and deferred amounts
  • Handles benefactor status and shipping basis changes

3. customer_subscriptions()

  • AJAX handler for retrieving customer subscriptions
  • Returns subscription options for customer management interface

4. subscription_duplicates()

  • Handles duplicate subscription detection
  • Works with frontend AJAX to find potential duplicate subscriptions

WordPress Integration

The controller is integrated with WordPress through various hooks that handle different aspects of subscription management:

Payment Processing Hooks

New Subscription Creation 

add_action('woocommerce_subscription_payment_complete', $controller, 'subscription_payment_complete', 30, 1);
add_action('jc_new_subscription_payment_complete_async', $controller, 'new_subscription_payment_complete', 10, 1);
  • subscription_payment_complete: Initial hook that triggers when a new subscription payment is completed
  • new_subscription_payment_complete: Async handler that:
    • Initializes subscription data
    • Sets up circulation management
    • Configures start/expiry issues
    • Sets copies owed and other parameters
    • Generates shipping soundex and address keys
    • Creates activity records

Subscription Renewal 

add_action('woocommerce_subscription_renewal_payment_complete', $controller, 'renewal_payment_complete', 30, 2);
add_action('jc_renewal_payment_complete_async', $controller, 'subscription_renewed', 10, 2);
  • renewal_payment_complete: Handles renewal payment completion
  • subscription_renewed: Async handler that:
    • Updates subscription data for renewal
    • Adjusts copies owed and expiry dates
    • Creates renewal activity records

Subscription Update Hooks

Address and SKU Updates 

add_action('woocommerce_update_subscription', $controller, 'maybe_update_address_keys', 99, 2);
add_action('woocommerce_saved_order_items', $controller, 'maybe_update_sku', 99, 2);
  • maybe_update_address_keys: Updates shipping and billing address keys when subscription details change
  • maybe_update_sku: Updates product SKU information when order items are modified

Subscription Deletion 

add_action('woocommerce_subscription_deleted', $controller, 'subscription_deleted', 10, 1);
  • subscription_deleted: Cleans up subscription data when a subscription is deleted
    • Removes custom data from the database
    • Handles cleanup of related records

Activity Tracking Hooks

The controller creates activity records for various subscription events:

add_action('journal_subscription_created', ...);
add_action('journal_subscription_renewed', ...);
add_action('journal_subscription_merged', ...);
add_action('journal_subscription_converted_to_gift', ...);
add_action('journal_subscription_edited', ...);
add_action('journal_subscription_auto_renewed', ...);
add_action('journal_subscription_pending_renewal_created', ...);
add_action('journal_subscription_batch_subscription_shipping_updated', ...);

Each of these hooks triggers activity logging for different subscription lifecycle events, maintaining an audit trail of subscription changes.

AJAX Endpoints

The controller provides several AJAX endpoints for frontend interaction:

add_action('wp_ajax_tsj_subscriptions_customer_subscriptions', $controller, 'customer_subscriptions');
add_action('wp_ajax_tsj_subscriptions_lookup_subscriptions', $controller, 'lookup_subscriptions');
add_action('wp_ajax_journal_expired_monthly_earning', $controller, 'expired_monthly_earning_handler');

These endpoints handle:

  • Customer subscription management
  • Subscription lookup and search
  • Expired monthly subscription processing

Integration with Other Controllers

The subscription controller works in conjunction with other controllers through action hooks:

Expiry Group Controller 

add_action('journal_subscription_created_before_save', $expiry_group_controller, 'subscription_created', 99, 2);
add_action('journal_subscription_renewed_before_save', $expiry_group_controller, 'payment_completed', 99, 3);
  • Handles expiry group management for new and renewed subscriptions

Shipping Batch Controller 

add_action('journal_batch_pulled', $shipping_batch_controller, 'create_activity_batch_pulled', 10, 2);
add_action('journal_batch_shipped', $shipping_batch_controller, 'create_activity_batch_shipped', 10, 1);
  • Manages shipping batch operations and related activity logging

Entitlements Controller 

add_action('journal_subscription_upgraded', $entitlements_controller, 'handle_upgrade_entitlement', 10, 5);
add_action('jc_entitlement_created_scheduled', $entitlements_controller, 'maybe_assign_default_product', 10, 1);
  • Handles entitlement management for subscription upgrades and new entitlements

Integration with Other Components

The controller works closely with:

  1. TSJ_Subscription class for subscription data management
  2. TSJ_Issue class for issue-related operations
  3. TSJ_Shipping_Batch_Controller for shipping management
  4. TSJ_Expiry_Group_Controller for expiry group management
  5. Journal_Entitlements_Controller for entitlement management

Security Considerations

  • Implements proper permission checks for admin actions
  • Uses WordPress nonce verification for AJAX requests
  • Validates user capabilities before performing sensitive operations

Error Handling

  • Logs errors using WooCommerce logger
  • Implements proper error checking for database operations
  • Provides feedback for failed operations

Best Practices

  1. Always use the factory function tsj_subscriptions_get_subscription() to create subscription instances
  2. Use proper action hooks for subscription lifecycle events
  3. Implement proper error handling and logging
  4. Follow WordPress coding standards and security practices

This controller is a central component of the TSJ Subscriptions plugin, handling the core business logic for subscription management and integration with WordPress and WooCommerce.