### Plugin Initialization and Configuration in PHP

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

Manages global plugin settings and options using a singleton pattern. Includes functions to get, update, and delete options, with prefix handling for ECPay specific settings. Requires WordPress and WooCommerce environments.

```php
// Initialize the plugin
RY_WT();

// Get plugin options with prefix handling
$merchant_id = RY_WT::get_option('ecpay_gateway_MerchantID');
$auto_get_shipping = RY_WT::get_option('ecpay_shipping_auto_get_no', 'yes');

// Update plugin options
RY_WT::update_option('enabled_ecpay_gateway', 'yes');
RY_WT::update_option('enabled_newebpay_shipping', 'no');

// Delete plugin options
RY_WT::delete_option('old_setting_key');

// Check if ECPay gateway is enabled
if ('yes' === RY_WT::get_option('enabled_ecpay_gateway', 'no')) {
    // ECPay gateway functionality is available
}
```

--------------------------------

### Plugin Initialization and Configuration

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

This section details how to initialize the plugin and manage its global settings using provided functions. It covers getting, updating, and deleting plugin options, along with checking the status of specific gateways.

```APIDOC
## Plugin Initialization and Configuration

### Description
Initialize the plugin and manage global settings through a singleton pattern. Access and modify plugin options with prefix handling.

### Method
Various static methods provided by the main plugin class.

### Endpoint
N/A (Internal Plugin Functions)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
// Initialize the plugin
RY_WT();

// Get plugin options with prefix handling
$merchant_id = RY_WT::get_option('ecpay_gateway_MerchantID');
$auto_get_shipping = RY_WT::get_option('ecpay_shipping_auto_get_no', 'yes');

// Update plugin options
RY_WT::update_option('enabled_ecpay_gateway', 'yes');
RY_WT::update_option('enabled_newebpay_shipping', 'no');

// Delete plugin options
RY_WT::delete_option('old_setting_key');

// Check if ECPay gateway is enabled
if ('yes' === RY_WT::get_option('enabled_ecpay_gateway', 'no')) {
    // ECPay gateway functionality is available
}
```

### Response
#### Success Response (200)
N/A (Internal Plugin Functions)

#### Response Example
N/A
```

--------------------------------

### Implement Custom 7-11 Convenience Store Shipping Method

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

Extends the abstract WC_Shipping_Method class to create a custom shipping method for ECPay's 7-11 convenience store pickup. It supports instance settings, calculates shipping costs based on potential surcharges (offshore islands and weight), and integrates with WooCommerce sessions for storing store selection information. Validation is included to ensure a store is selected before checkout completion.

```php
class RY_ECPay_Shipping_CVS_711 extends RY_WT_WC_Shipping_Method {

    public function __construct($instance_id = 0) {
        $this->id = 'ry_ecpay_shipping_cvs_711';
        $this->method_title = '7-11 Convenience Store Pickup';
        $this->method_description = 'ECPay 7-11 store pickup service';

        $this->supports = [
            'shipping-zones',
            'instance-settings',
        ];

        $this->init();
    }

    public static function get_support_temp() {
        return ['1'];  // Normal temperature only
    }

    public function calculate_shipping($package = []) {
        $rate = [
            'id' => $this->get_rate_id(),
            'label' => $this->title,
            'cost' => $this->cost,
            'package' => $package,
        ];

        // Add offshore island surcharge
        if ($this->cost_offisland > 0) {
            $cvs_info = WC()->session->get('ry_ecpay_cvs_info', []);
            if (!empty($cvs_info['CVSOutSide'])) {
                $rate['cost'] += $this->cost_offisland;
                $rate['label'] .= ' (+offshore)';
            }
        }

        // Add weight-based surcharge
        $weight = 0;
        foreach ($package['contents'] as $item) {
            $weight += $item['data']->get_weight() * $item['quantity'];
        }
        if ($weight > 5000 && $this->weight_plus_cost > 0) {
            $rate['cost'] += $this->weight_plus_cost;
        }

        $this->add_rate($rate);
    }
}

// Register shipping method
add_filter('woocommerce_shipping_methods', function($methods) {
    $methods['ry_ecpay_shipping_cvs_711'] = 'RY_ECPay_Shipping_CVS_711';
    return $methods;
});

// Validate shipping availability
add_action('woocommerce_checkout_process', function() {
    $chosen_methods = WC()->session->get('chosen_shipping_methods');
    if (!empty($chosen_methods[0]) && strpos($chosen_methods[0], 'ry_ecpay_shipping_cvs') !== false) {
        $cvs_info = WC()->session->get('ry_ecpay_cvs_info', []);
        if (empty($cvs_info['CVSStoreID'])) {
            wc_add_notice(__('Please select a convenience store', 'ry-woocommerce-tools'), 'error');
        }
    }
});
```

--------------------------------

### Implement Custom ECPay Credit Card Payment Gateway

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

Extends the abstract WC_Payment_Gateway class to create a custom ECPay credit card payment method. It includes setting payment limits (minimum and maximum amounts) and defines the process for handling payments, including order status updates and redirects. This gateway requires the RY_WT_WC_ECPay_Gateway_Api class for checkout form generation.

```php
class RY_ECPay_Gateway_Credit extends RY_WT_WC_Payment_Gateway {

    public function __construct() {
        $this->id = 'ry_ecpay_credit';
        $this->method_title = 'ECPay Credit Card';
        $this->has_fields = false;

        // Set payment limits
        $this->check_min_amount = 10;      // Minimum NT$10
        $this->check_max_amount = 200000;  // Maximum NT$200,000

        parent::__construct();

        $this->title = $this->get_option('title', 'Credit Card');
        $this->description = $this->get_option('description');
    }

    public function process_payment($order_id) {
        $order = wc_get_order($order_id);

        // Mark as pending payment
        $order->update_status('pending', __('Awaiting ECPay payment', 'ry-woocommerce-tools'));

        // Generate payment form and redirect
        return [
            'result' => 'success',
            'redirect' => $order->get_checkout_payment_url(true)
        ];
    }

    public function receipt_page($order_id) {
        $order = wc_get_order($order_id);
        $gateway_api = RY_WT_WC_ECPay_Gateway_Api::instance();
        $gateway_api->checkout_form($order, $this);
    }
}

// Register the gateway
add_filter('woocommerce_payment_gateways', function($gateways) {
    $gateways[] = 'RY_ECPay_Gateway_Credit';
    return $gateways;
});

// Check if gateway is available for current cart
$gateway = new RY_ECPay_Gateway_Credit();
if ($gateway->is_available()) {
    // Gateway available - amount within limits
} else {
    // Gateway unavailable - check min/max amount
}
```

--------------------------------

### Configure Admin Settings for ECPay Gateway (PHP)

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

This PHP code snippet adds a custom settings page to WooCommerce and defines fields for configuring the ECPay payment gateway. It includes options for enabling the gateway, entering Merchant ID, Hash Key, Hash IV, and a test mode toggle. It also implements basic validation to ensure the Merchant ID is provided when the gateway is enabled.

```php
// Add custom settings page
add_filter('woocommerce_get_settings_pages', function($settings) {
    $settings[] = include(RY_WT_PLUGIN_DIR . 'woocommerce/admin/settings/ry-tools-settings.php');
    return $settings;
});

// Define settings for ECPay gateway
$settings = [
    [
        'title' => __('ECPay Gateway Settings', 'ry-woocommerce-tools'),
        'type' => 'title',
        'id' => 'ecpay_gateway_settings',
    ],
    [
        'title' => __('Enable ECPay Gateway', 'ry-woocommerce-tools'),
        'type' => 'checkbox',
        'default' => 'no',
        'id' => RY_WT::OPTION_PREFIX . 'enabled_ecpay_gateway',
    ],
    [
        'title' => __('Merchant ID', 'ry-woocommerce-tools'),
        'type' => 'text',
        'id' => RY_WT::OPTION_PREFIX . 'ecpay_gateway_MerchantID',
        'desc' => __('Enter your ECPay Merchant ID', 'ry-woocommerce-tools'),
    ],
    [
        'title' => __('Hash Key', 'ry-woocommerce-tools'),
        'type' => 'password',
        'id' => RY_WT::OPTION_PREFIX . 'ecpay_gateway_HashKey',
    ],
    [
        'title' => __('Hash IV', 'ry-woocommerce-tools'),
        'type' => 'password',
        'id' => RY_WT::OPTION_PREFIX . 'ecpay_gateway_HashIV',
    ],
    [
        'title' => __('Test Mode', 'ry-woocommerce-tools'),
        'type' => 'checkbox',
        'default' => 'yes',
        'id' => RY_WT::OPTION_PREFIX . 'ecpay_gateway_testmode',
        'desc' => __('Enable test mode for development', 'ry-woocommerce-tools'),
    ],
    [
        'type' => 'sectionend',
        'id' => 'ecpay_gateway_settings',
    ],
];

// Save settings with validation
add_action('woocommerce_update_options_rytools', function() {
    if ('yes' === RY_WT::get_option('enabled_ecpay_gateway', 'no')) {
        $merchant_id = RY_WT::get_option('ecpay_gateway_MerchantID');
        if (empty($merchant_id)) {
            WC_Admin_Settings::add_error(__('ECPay Merchant ID is required', 'ry-woocommerce-tools'));
            RY_WT::update_option('enabled_ecpay_gateway', 'no');
        }
    }
});
```

--------------------------------

### ECPay Payment Gateway Integration in PHP

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

Handles ECPay payment processing, including checkout form generation, payment status querying, and callback response handling. Integrates with WooCommerce order objects and ECPay API. Requires WooCommerce and ECPay specific classes.

```php
// ECPay checkout form generation
$gateway_api = RY_WT_WC_ECPay_Gateway_Api::instance();
$order = wc_get_order(123);
$gateway = new RY_ECPay_Gateway_Credit();

// Generate payment form - automatically posts to ECPay
$gateway_api->checkout_form($order, $gateway);

// Query payment status from ECPay
$payment_info = $gateway_api->get_info($order);
if ($payment_info && isset($payment_info['TradeStatus'])) {
    switch ($payment_info['TradeStatus']) {
        case '1': // Payment successful
            $order->payment_complete();
            break;
        case '0': // Payment failed
            $order->update_status('failed');
            break;
        case '2': // Pending
            $order->update_status('pending');
            break;
    }
}

// Handle ECPay callback response
add_action('woocommerce_api_ry_ecpay_callback', function() {
    $response = RY_WT_WC_ECPay_Gateway_Response::instance();
    $response->check_callback_response($_POST);
});
```

--------------------------------

### ECPay Payment Gateway Integration

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

This section covers the integration with the ECPay payment gateway, including generating checkout forms, querying payment status, and handling ECPay callback responses for various payment methods.

```APIDOC
## ECPay Payment Gateway Integration

### Description
Process payments through ECPay's multiple payment methods including credit cards, ATM, convenience store payments, and more. This includes generating checkout forms, querying payment status, and handling ECPay callback responses.

### Method
Various methods provided by `RY_WT_WC_ECPay_Gateway_Api` and `RY_ECPay_Gateway_Credit` classes.

### Endpoint
`woocommerce_api/ry_ecpay_callback` (for handling callbacks)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (for callback, typically uses `$_POST` data)

### Request Example
```php
// ECPay checkout form generation
$gateway_api = RY_WT_WC_ECPay_Gateway_Api::instance();
$order = wc_get_order(123);
$gateway = new RY_ECPay_Gateway_Credit();

// Generate payment form - automatically posts to ECPay
$gateway_api->checkout_form($order, $gateway);

// Query payment status from ECPay
$payment_info = $gateway_api->get_info($order);
if ($payment_info && isset($payment_info['TradeStatus'])) {
    switch ($payment_info['TradeStatus']) {
        case '1': // Payment successful
            $order->payment_complete();
            break;
        case '0': // Payment failed
            $order->update_status('failed');
            break;
        case '2': // Pending
            $order->update_status('pending');
            break;
    }
}

// Handle ECPay callback response
add_action('woocommerce_api_ry_ecpay_callback', function() {
    $response = RY_WT_WC_ECPay_Gateway_Response::instance();
    $response->check_callback_response($_POST);
});
```

### Response
#### Success Response (200)
ECPay callback responses are handled internally to update order status. The `get_info` method returns payment status details.
- **TradeStatus** (string) - The status of the trade ('1' for success, '0' for failed, '2' for pending).

#### Response Example
```json
{
  "TradeStatus": "1"
}
```
```

--------------------------------

### Manage Scheduled Tasks for Time Sync (PHP)

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

This PHP code manages WordPress cron jobs for time synchronization. It schedules a daily event for 'ry_check_ntp_time' on plugin activation and removes it on deactivation. The action hook 'ry_check_ntp_time' checks the server's time against an NTP server, logs an error and notifies the admin if the difference exceeds 5 minutes. It also includes a WP-CLI command for manual cron execution.

```php
// Plugin activation - schedule cron tasks
register_activation_hook(__FILE__, function() {
    if (!wp_next_scheduled('ry_check_ntp_time')) {
        RY_WT::update_option('ntp_time_error', false);
        wp_schedule_event(time(), 'daily', 'ry_check_ntp_time');
    }
});

// Plugin deactivation - remove scheduled tasks
register_deactivation_hook(__FILE__, function() {
    wp_unschedule_hook('ry_check_ntp_time');
});

// Handle NTP time check cron
add_action('ry_check_ntp_time', function() {
    $ntp_server = 'time.google.com';
    $socket = @fsockopen($ntp_server, 123, $errno, $errstr, 5);

    if ($socket) {
        // Check time difference
        $local_time = time();
        // ... NTP protocol implementation ...

        if (abs($time_diff) > 300) { // 5 minutes difference
            RY_WT::update_option('ntp_time_error', true);
            // Send admin notification
            wp_mail(
                get_option('admin_email'),
                __('RY Tools: Server time synchronization warning', 'ry-woocommerce-tools'),
                sprintf(__('Server time differs by %d seconds', 'ry-woocommerce-tools'), $time_diff)
            );
        } else {
            RY_WT::update_option('ntp_time_error', false);
        }
        fclose($socket);
    }
});

// Manual cron execution for testing
if (defined('WP_CLI') && WP_CLI) {
    WP_CLI::add_command('rytools cron', function($args) {
        do_action('ry_check_ntp_time');
        WP_CLI::success('Cron task executed successfully');
    });
}
```

--------------------------------

### Integrate ECPay Shipping Methods and Auto-Generate Logistics Codes (PHP)

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

This snippet demonstrates how to add ECPay shipping methods (7-11, FamilyMart, Hi-Life, OK Mart, Post delivery, Black Cat) to WooCommerce. It also includes functionality to capture convenience store selection during checkout and automatically generate ECPay logistics codes when an order status changes to 'processing'. Dependencies include the RY_WT_WC_ECPay_Shipping class and related API integrations.

```php
// Add ECPay shipping methods
$shipping_instance = RY_WT_WC_ECPay_Shipping::instance();

// Available shipping method classes
$methods = [
    'ry_ecpay_shipping_cvs_711' => 'RY_ECPay_Shipping_CVS_711',        // 7-11 pickup
    'ry_ecpay_shipping_cvs_family' => 'RY_ECPay_Shipping_CVS_Family',  // FamilyMart
    'ry_ecpay_shipping_cvs_hilife' => 'RY_ECPay_Shipping_CVS_Hilife',  // Hi-Life
    'ry_ecpay_shipping_cvs_ok' => 'RY_ECPay_Shipping_CVS_Ok',          // OK Mart
    'ry_ecpay_shipping_home_post' => 'RY_ECPay_Shipping_Home_Post',    // Post delivery
    'ry_ecpay_shipping_home_tcat' => 'RY_ECPay_Shipping_Home_Tcat',    // Black Cat
];

// Process convenience store selection
add_action('woocommerce_checkout_update_order_review', function($post_data) {
    parse_str($post_data, $data);

    // Store selected CVS information
    if (isset($data['RY_CVSStoreID'])) {
        WC()->session->set('ry_ecpay_cvs_info', [
            'LogisticsSubType' => $data['RY_LogisticsSubType'],
            'CVSStoreID' => $data['RY_CVSStoreID'],
            'CVSStoreName' => $data['RY_CVSStoreName'],
            'CVSAddress' => $data['RY_CVSAddress'],
            'CVSTelephone' => $data['RY_CVSTelephone'],
            'CVSOutSide' => $data['RY_CVSOutSide']
        ]);
    }
});

// Auto-generate shipping code when order status changes
add_action('woocommerce_order_status_processing', function($order_id, $order) {
    if ('yes' === RY_WT::get_option('ecpay_shipping_auto_get_no', 'yes')) {
        $shipping_method = $order->get_shipping_method();
        if (strpos($shipping_method, 'ECPay') !== false) {
            // API call to generate shipping code
            $shipping_api = RY_WT_WC_ECPay_Shipping_Api::instance();
            $result = $shipping_api->create_order($order);

            if ($result && isset($result['RtnCode']) && $result['RtnCode'] == '1') {
                $order->add_order_note('ECPay shipping code: ' . $result['AllPayLogisticsID']);
                $order->update_meta_data('_ecpay_shipping_id', $result['AllPayLogisticsID']);
                $order->save();
            }
        }
    }
}, 10, 2);

```

--------------------------------

### Convert Taiwanese Bank Codes to Localized Names (PHP)

Source: https://context7.com/richeryang/ry-woocommerce-tools/llms.txt

This utility function, `rywt_bank_code_to_name`, converts Taiwanese bank codes into their corresponding localized bank names. It is useful for displaying bank information clearly to customers during payment or in order notes. The function takes a bank code as input and returns the localized name. It can be used in various contexts, such as displaying payment details in the admin panel or adding information to order notes.

```php
// Get bank name from code
$bank_name = rywt_bank_code_to_name('004');  // Returns: Taiwan Bank (localized)
$bank_name = rywt_bank_code_to_name('012');  // Returns: Taipei Fubon Bank (localized)
$bank_name = rywt_bank_code_to_name('822');  // Returns: CTBC Bank (localized)

// Use in order notes
$bank_code = $order->get_meta('_ecpay_payment_bank_code');
$bank_name = rywt_bank_code_to_name($bank_code);
$order->add_order_note(sprintf(
    __('Customer selected ATM transfer via %s (Code: %s)', 'ry-woocommerce-tools'),
    $bank_name,
    $bank_code
));

// Display in admin panel
if ($payment_method === 'ry_ecpay_atm') {
    $bank_code = $order->get_meta('_ecpay_payment_bank_code');
    $account = $order->get_meta('_ecpay_payment_account');
    echo sprintf(
        '<p>Bank: %s<br>Virtual Account: %s</p>',
        esc_html(rywt_bank_code_to_name($bank_code)),
        esc_html($account)
    );
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.