Hooks Documentation

Overview

This document contains comprehensive documentation of all hooks available in the Automatic Product Categories for WooCommerce plugin.

Plugin Custom Hooks

1. Action Hooks

apc_before_table

• Parameters: None
• Description: Fired before the rules table is displayed in the admin panel
• Pro Usage: Adds search box before the rules table

apc_save_rule

• Parameters: $formatted_data (array with formatted rule data)
• Description: Fired when a rule is saved (both create and update operations)
• Usage: Allows performing custom actions when rules are saved to the database

apc_delete_rule

• Parameters: $id (int, rule ID)
• Description: Fired when a single rule is deleted from the database

apc_delete_all_rule

• Parameters: None
• Description: Fired when all rules are deleted from the database (e.g., during import with overwrite)

php_apc_ran_ajax_rules

• Parameters: None
• Description: Fired after rules are executed via AJAX request
• Pro Usage: Sends JSON response with detailed rule execution results

2. Filter Hooks

berrypress_apc_rule_class

• Parameters: $class_name (string, default: 'Penthouse\AutomaticProductCategories\Rule')
• Returns: Modified class name
• Description: Allows replacing the Rule class with a custom implementation
• Pro Usage: Returns ProRule::class to enable Pro features

berrypress_apc_rules_table_class

• Parameters: $class_name (string, default: APCRulesTable::class)
• Returns: Modified class name
• Description: Allows replacing the Rules Table database handler class
• Pro Usage: Returns APCProRulesTable::class to enable Pro features

automatic_product_categories_list_table_class

• Parameters: $class_name (string, default: RulesListTable::class)
• Returns: Modified class name
• Description: Allows replacing the WP_List_Table implementation for rules display
• Pro Usage: Returns RulesListTablePro::class to add Pro features

automatic_product_categories_submitted_rule

• Parameters:
  • $ruleArray (array, sanitized rule data)
  • $ruleData (array, raw submitted data)
• Returns: Modified rule array
• Description: Allows modifying rule data before it's converted to a Rule object
• Pro Usage: Adds support for rule groups

automatic_product_categories_rule_conditions

• Parameters: $conditions (array of available condition types)
• Returns: Modified conditions array
• Description: Allows adding custom condition types for rules
• Pro Usage: Adds support for custom taxonomies beyond product_cat, product_tag, and attributes

php_apc_action_item_id

• Parameters:
  • $itemId (int, term/item ID)
  • $taxonomy (string, taxonomy name or action type)
  • $product (WC_Product object)
  • $removing (bool, true if removing term, false if adding)
• Returns: Modified item ID (return 0 to skip the action)
• Description: Filters the item ID before applying an action to a product. Allows modifying or preventing term assignment/removal
• Pro Usage: Returns 0 during dry runs to prevent actual changes, tracks changes for results display

WordPress Core Hooks Used

Action Hooks

penthouse_apc_daily_rules

• Function: processProductsDaily()
• Description: Scheduled event that runs rules configured for daily execution
• Schedule: Daily (if any rules are enabled for scheduled execution)

wp_ajax_php_apc_run_rule

• Function: runRuleAjax() (Free), beforeRunRuleAjax() (Pro)
• Description: Handles AJAX requests to run rules manually from admin interface

JavaScript Hooks

The plugin uses WordPress JavaScript hooks system (wp.hooks) for frontend interactions:

JavaScript Action Hooks

php-apc-ran-rules

• Parameters: response (AJAX response), request (original request data)
• Description: Fired after rules are executed via AJAX
• Pro Usage: Displays detailed results modal with affected products

JavaScript Filter Hooks

php-apc-run-rules

• Parameters: data (serialized form data)
• Returns: Modified data string
• Description: Allows modifying request data before sending to server
• Pro Usage: Appends &dry=1 parameter when dry run checkbox is checked

Scheduled Hooks

penthouse_apc_daily_rules

• Function: processProductsDaily()
• Description: Scheduled task executed daily
• Actions:
  • Processes all products against rules enabled for scheduled execution
  • Runs rules enabled for daily schedule
• Schedule: Only active when at least one rule has daily scheduling enabled

Usage Examples

Adding custom condition type

// Add custom condition for checking product vendor
add_filter('automatic_product_categories_rule_conditions', function($conditions) {
    $conditions['vendor'] = [
        'title' => 'Vendor',
        'type' => 'string',
        'test' => function($condition, $product) {
            $vendor = get_post_meta($product->get_id(), '_vendor', true);
            return $condition->stringValueMatch($vendor);
        }
    ];
    return $conditions;
});

Modifying rule before processing

// Add custom data to rule before it's saved
add_filter('automatic_product_categories_submitted_rule', function($ruleArray, $ruleData) {
    // Add custom priority field
    if (isset($ruleData['custom_priority'])) {
        $ruleArray['priority'] = (int) $ruleData['custom_priority'];
    }
    return $ruleArray;
}, 10, 2);

Tracking rule actions

// Log when rules modify products
add_filter('php_apc_action_item_id', function($itemId, $taxonomy, $product, $removing) {
    error_log(sprintf(
        'Rule %s term %d (%s) for product %d',
        $removing ? 'removed' : 'added',
        $itemId,
        $taxonomy,
        $product->get_id()
    ));
    return $itemId;
}, 10, 4);

Preventing action in specific cases

// Prevent removing the last category from products
add_filter('php_apc_action_item_id', function($itemId, $taxonomy, $product, $removing) {
    if ($removing && $taxonomy === 'product_cat') {
        $categories = wp_get_object_terms($product->get_id(), 'product_cat');
        if (count($categories) <= 1) {
            // Return 0 to skip this action
            return 0;
        }
    }
    return $itemId;
}, 10, 4);

Performing action when rule is saved

// Clear cache when rules are modified
add_action('apc_save_rule', function($formatted_data) {
    // Clear custom cache
    wp_cache_delete('my_custom_rules_cache');
    
    // Log the change
    error_log('Rule saved: ' . $formatted_data['name']);
});

Replacing rule class with custom implementation

// Use custom Rule class with additional features
add_filter('berrypress_apc_rule_class', function($class) {
    require_once(__DIR__ . '/includes/CustomRule.php');
    return 'MyPlugin\\CustomRule';
});

Hook Availability

Hook Name	Free Version	Pro Version	Notes
Action Hooks
apc_before_table	✅	✅	Enhanced in Pro (search box)
apc_save_rule	✅	✅	Database operations
apc_delete_rule	✅	✅	Single rule deletion
apc_delete_all_rule	✅	✅	Bulk deletion
php_apc_ran_ajax_rules	✅	✅	Enhanced in Pro (detailed results)
Filter Hooks
berrypress_apc_rule_class	✅	✅	Pro uses ProRule::class
berrypress_apc_rules_table_class	✅	✅	Pro uses APCProRulesTable::class
automatic_product_categories_list_table_class	✅	✅	Pro uses RulesListTablePro::class
automatic_product_categories_submitted_rule	✅	✅	Enhanced in Pro (groups support)
automatic_product_categories_rule_conditions	✅	✅	Enhanced in Pro (custom taxonomies)
php_apc_action_item_id	✅	✅	Enhanced in Pro (dry run, tracking)
WordPress Core Hooks
penthouse_apc_daily_rules	✅	✅	Scheduled execution
wp_ajax_php_apc_run_rule	✅	✅	Manual execution
JavaScript Hooks
php-apc-run-rules (filter)	✅	✅	Enhanced in Pro (dry run)
php-apc-ran-rules (action)	✅	✅	Enhanced in Pro (results modal)

Notes

• Pro version enhances many free hooks with additional functionality
• JavaScript hooks use WordPress's wp.hooks API for consistency
• Custom taxonomies support in Pro version demonstrates extensibility via hooks
• The plugin follows WordPress coding standards for hook naming and documentation