چرا خطاهای AJAX شما بی‌صدا ناپدید می‌شوند؟ راهنمای wp_send_json_error

چرا مدیریت خطای AJAX حیاتی است؟

تابع wp_send_json_error چیست؟

امضای تابع و پارامترها

function wp_send_json_error( $data = null, $status_code = null, $options = 0 ) {
    $response = array( 'success' => false );
    if ( null !== $data ) {
        $response['data'] = $data;
    }
    wp_send_json( $response, $status_code, $options );
}

سازوکار داخلی تابع

ساختار پاسخ JSON

{
  "success": false,
  "data": {
    "code": "invalid_nonce",
    "message": "درخواست نامعتبر است",
    "status": 403
  }
}

کدهای وضعیت HTTP

if ( ! check_ajax_referer( 'myplugin_nonce', 'nonce', false ) ) {
    wp_send_json_error(
        array( 'message' => 'درخواست نامعتبر است' ),
        403
    );
}

کاربردهای عملی در افزونه

add_action( 'wp_ajax_myplugin_process_order', 'myplugin_process_order_handler' );
function myplugin_process_order_handler() {
    if ( ! check_ajax_referer( 'myplugin_order_nonce', 'nonce', false ) ) {
        wp_send_json_error( array(
            'code'    => 'invalid_nonce',
            'message' => 'نشست شما منقضی شده است. صفحه را بازخوانی کنید.',
        ), 403 );
    }

    if ( ! current_user_can( 'manage_woocommerce' ) ) {
        wp_send_json_error( array(
            'code'    => 'insufficient_permissions',
            'message' => 'دسترسی کافی ندارید',
        ), 403 );
    }

    $order_id = isset( $_POST['order_id'] ) ? absint( $_POST['order_id'] ) : 0;
    if ( ! $order_id ) {
        wp_send_json_error( array(
            'code'    => 'missing_order_id',
            'message' => 'شناسه سفارش نامعتبر است',
        ), 400 );
    }

    $order = wc_get_order( $order_id );
    if ( ! $order ) {
        wp_send_json_error( array(
            'code'    => 'order_not_found',
            'message' => 'سفارش پیدا نشد',
        ), 404 );
    }

    try {
        myplugin_process_order( $order );
        wp_send_json_success( array( 'order_id' => $order_id ) );
    } catch ( Exception $e ) {
        wp_send_json_error( array(
            'code'    => 'processing_failed',
            'message' => 'خطا در پردازش: ' . $e->getMessage(),
        ), 500 );
    }
}

function myplugin_validate_form_handler() {
    check_ajax_referer( 'myplugin_form_nonce', 'nonce' );

    $errors = array();

    $email = isset( $_POST['email'] ) ? sanitize_email( $_POST['email'] ) : '';
    if ( ! is_email( $email ) ) {
        $errors['email'] = 'ایمیل نامعتبر است';
    }

    $name = isset( $_POST['name'] ) ? sanitize_text_field( $_POST['name'] ) : '';
    if ( empty( $name ) ) {
        $errors['name'] = 'نام الزامی است';
    }

    if ( ! empty( $errors ) ) {
        wp_send_json_error( array(
            'code'    => 'validation_failed',
            'message' => 'لطفاً خطاها را بررسی کنید',
            'errors'  => $errors,
        ), 422 );
    }

    wp_send_json_success( array( 'message' => 'فرم با موفقیت ثبت شد' ) );
}

jQuery.post(
    mypluginData.ajaxUrl,
    formData,
    function( response ) {
        if ( response.success ) {
            showSuccess( response.data.message );
            return;
        }

        // نمایش پیام خطای کلی
        showError( response.data.message );

        // نمایش خطاهای فیلد به فیلد
        if ( response.data.errors ) {
            jQuery.each( response.data.errors, function( field, message ) {
                jQuery( '[name="' + field + '"]' ).addClass( 'has-error' );
                jQuery( '[name="' + field + '"]' ).next( '.error-message' ).text( message );
            } );
        }
    }
);

اشکال‌زدایی خطاهای AJAX

add_action( 'wp_ajax_myplugin_debug_test', 'myplugin_debug_handler' );
function myplugin_debug_handler() {
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        wp_send_json_error( array( 'message' => 'حالت دیباگ غیرفعال است' ), 400 );
    }

    if ( ! check_ajax_referer( 'myplugin_debug_nonce', 'nonce', false ) ) {
        wp_send_json_error( array(
            'code'    => 'nonce_failed',
            'message' => 'nonce نامعتبر',
            'received_nonce' => isset( $_POST['nonce'] ) ? $_POST['nonce'] : 'missing',
        ), 403 );
    }

    wp_send_json_success( array( 'message' => 'همه چیز درست است' ) );
}

نکات امنیتی و اشتباهات رایج

if ( is_wp_error( $result ) ) {
    error_log( sprintf(
        '[myplugin] Order processing failed: %s | Order ID: %d',
        $result->get_error_message(),
        $order_id
    ) );

    wp_send_json_error( array(
        'code'    => 'processing_failed',
        'message' => 'خطا در پردازش سفارش. لطفاً با پشتیبانی تماس بگیرید.',
    ), 500 );
}

تحلیل فنی پیشرفته

پرسش‌های پرتکرار

نتیجه و مسیر ادامه