WordPress AJAX Cheatsheet (Nâng cao)

Dưới đây là bản WordPress AJAX Cheatsheet nâng cao, dành cho lập trình viên muốn thực hiện xử lý bất đồng bộ (AJAX) giữa frontend và backend trong theme/plugin WordPress một cách đúng chuẩn, bảo mật và hiệu quả.

---

1. Cơ chế hoạt động của AJAX trong WordPress

• AJAX request được gửi tới:
  /wp-admin/admin-ajax.php
• WordPress xử lý request dựa vào action và hook wp_ajax_{action} hoặc wp_ajax_nopriv_{action}
• AJAX có thể dùng cả ở frontend (client) lẫn admin (backend)

---

2. Gửi AJAX từ JavaScript (fetch)

📋 Copyfetch(ajaxurl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
  },
  body: new URLSearchParams({
    action: 'my_ajax_action',
    security: my_script_data.nonce,
    name: 'Johnny'
  })
})
.then(res => res.json())
.then(data => console.log(data));

---

3. Khai báo biến ajaxurl và nonce từ PHP

📋 Copyadd_action('wp_enqueue_scripts', 'my_enqueue_script');
function my_enqueue_script() {
    wp_enqueue_script('my-ajax', get_template_directory_uri() . '/js/my-ajax.js', ['jquery'], null, true);
    
    wp_localize_script('my-ajax', 'my_script_data', [
        'ajaxurl' => admin_url('admin-ajax.php'),
        'nonce' => wp_create_nonce('my_ajax_nonce')
    ]);
}

---

4. Xử lý AJAX ở PHP

📋 Copyadd_action('wp_ajax_my_ajax_action', 'handle_my_ajax');
add_action('wp_ajax_nopriv_my_ajax_action', 'handle_my_ajax'); // Cho user chưa login

function handle_my_ajax() {
    check_ajax_referer('my_ajax_nonce', 'security');

    $name = sanitize_text_field($_POST['name']);

    wp_send_json_success([
        'message' => "Xin chào $name!"
    ]);

    wp_die();
}

---

5. Sử dụng jQuery AJAX (cũ nhưng vẫn phổ biến)

📋 CopyjQuery.post(my_script_data.ajaxurl, {
    action: 'my_ajax_action',
    security: my_script_data.nonce,
    name: 'Johnny'
}, function(response) {
    if (response.success) {
        alert(response.data.message);
    }
});

---

6. AJAX từ trang admin

• Có thể dùng cùng admin-ajax.php, không cần wp_ajax_nopriv
• Vẫn nên tạo nonce riêng và truyền qua admin_enqueue_scripts

---

7. AJAX trong shortcode, widget, template

Chỉ cần bạn gọi wp_localize_script() và truyền biến nonce + ajaxurl, bạn có thể gửi từ bất kỳ nơi nào ở frontend.

---

8. Trả kết quả dạng JSON

📋 Copywp_send_json_success(['key' => 'value']); // Status 200
wp_send_json_error(['error' => 'Something went wrong']); // Status 400

Hoặc trả thô:

📋 Copyecho json_encode(['status' => 'ok']);
wp_die();

---

9. AJAX Upload File

📋 Copyconst formData = new FormData();
formData.append('action', 'upload_file');
formData.append('security', my_script_data.nonce);
formData.append('file', fileInput.files[0]);

fetch(my_script_data.ajaxurl, {
  method: 'POST',
  body: formData
})
.then(res => res.json())
.then(result => console.log(result));

PHP:

📋 Copyadd_action('wp_ajax_upload_file', 'handle_upload');
function handle_upload() {
    check_ajax_referer('my_ajax_nonce', 'security');

    if (!empty($_FILES['file']['name'])) {
        $upload = wp_handle_upload($_FILES['file'], ['test_form' => false]);
        if (!isset($upload['error'])) {
            wp_send_json_success(['url' => $upload['url']]);
        }
    }

    wp_send_json_error(['error' => 'Upload thất bại']);
}

---

10. Best Practices

• Luôn dùng check_ajax_referer() để bảo vệ
• Sử dụng sanitize_text_field() và esc_* functions để lọc input
• Luôn gọi wp_die() để kết thúc request
• Trả về JSON rõ ràng, dễ debug
• Sử dụng wp_localize_script() hoặc wp_add_inline_script() để truyền biến từ PHP sang JS

---

11. AJAX trong block editor (Gutenberg)

Khi dùng @wordpress/api-fetch, bạn có thể gọi API tương tự:

📋 Copyimport apiFetch from '@wordpress/api-fetch';

apiFetch({
  path: '/wp-admin/admin-ajax.php',
  method: 'POST',
  data: {
    action: 'my_ajax_action',
    security: my_script_data.nonce
  }
}).then(response => {
  console.log(response);
});

---

12. Các hook AJAX liên quan

Hook	Mô tả
wp_ajax_{action}	Cho người dùng đã đăng nhập
wp_ajax_nopriv_{action}	Cho khách (chưa đăng nhập)
admin_enqueue_scripts	Gắn JS vào admin
wp_enqueue_scripts	Gắn JS vào frontend

---

13. Debug AJAX

• Mở tab Network → Xem request tới admin-ajax.php
• Kiểm tra response, status code, headers
• Bật WP_DEBUG và WP_DEBUG_LOG trong wp-config.php
• Dùng error_log() trong hàm xử lý để ghi lỗi vào wp-content/debug.log