1. GIỚI THIỆU

1.1. Plugin Là Gì?

WP Elasticsearch là plugin chuyên nghiệp giúp đồng bộ dữ liệu WooCommerce lên hệ thống Elasticsearch với khả năng:

  • 🔄 Đồng bộ real-time tự động khi có thay đổi
  • 📦 Bulk indexing hàng loạt sản phẩm
  • 🖥️ WP-CLI support cho server operations
  • 📊 Console monitoring theo dõi chi tiết
  • 🔌 Hooks/Filters mở rộng linh hoạt

1.2. Tính Năng Chính v1.3.7

✨ Đồng Bộ Thông Minh

  • Real-time sync tự động
  • 16 WordPress hooks optimized
  • Batch processing
  • Lock mechanism
  • Product Configuration

🔄 Auto Verify & Sync

  • Kiểm tra tự động mỗi giờ
  • Phát hiện sản phẩm thiếu
  • Xóa sản phẩm thừa
  • Sửa sản phẩm lỗi
  • Database logging

📊 Database Logging

  • Persistent audit trail
  • Phân loại log chi tiết
  • Trang Quản Lý Nhật Ký
  • Tìm kiếm & lọc
  • Pagination

🚀 Hiệu Năng Cao

  • Optimized queries
  • Config-driven batch size
  • Auto reset stuck
  • Async cURL
  • Code consolidation

1.3. Yêu Cầu Hệ Thống

  • WordPress 5.0 trở lên
  • WooCommerce 3.0 trở lên
  • PHP 7.4 trở lên (khuyến nghị PHP 8.0+)
  • MySQL 5.7+ hoặc MariaDB 10.2+
  • Elasticsearch 7.x hoặc 8.x
  • Memory limit: 256MB+ (khuyến nghị 512MB)
  • Max execution time: 300s+ cho bulk operations

2. CÀI ĐẶT BAN ĐẦU

Bước 1: Kích Hoạt Plugin

  1. Vào WordPress Admin → Plugins → Installed Plugins
  2. Tìm WP Elasticsearch
  3. Click Activate (Kích hoạt)
Plugin đã sẵn sàng sử dụng!
Lưu ý: Plugin sẽ tự động:
  • Tạo bảng wp_es_product_index (tracking products)
  • Tạo bảng wp_es_console_logs (monitoring logs)
  • Đăng ký 18 WordPress hooks tự động
  • Khởi tạo cron jobs (reset stuck, cleanup logs)

Bước 2: Kiểm Tra Menu

Sau khi kích hoạt, bạn sẽ thấy menu mới Elastic Search:

  • 📦 Index Product - Quản lý đồng bộ sản phẩm
  • 🏷️ Index Term - Đồng bộ categories/tags (coming soon)
  • 📋 Index Order - Đồng bộ orders (coming soon)
  • 🗑️ Delete Products - Xóa products khỏi ES (coming soon)
  • ⚙️ Config - Cấu hình kết nối Elasticsearch

3. CẤU HÌNH ELASTICSEARCH

3.1. Truy Cập Trang Cấu Hình

WordPress Admin → Elastic Search → Config

3.2. List Module (Chọn Module Cần Tối Ưu)

Chọn các module muốn đồng bộ lên Elasticsearch:

  • ☑️ User - Đồng bộ users (coming soon)
  • ☑️ Term - Đồng bộ categories/tags (coming soon)
  • ☑️ Product - Đồng bộ WooCommerce products ✅
  • ☑️ Order - Đồng bộ orders (coming soon)

3.3. Configuration (Thông Tin Kết Nối)

Elasticsearch URL
Ví dụ: http://localhost
Hoặc: http://192.168.1.100
Hoặc: https://es.domain.com
Lưu ý: Không nhập cổng (port) vào URL
Port
Mặc định: 9200
Authentication Type

Chọn 1 trong 2 phương thức:

  1. No Authentication - Không yêu cầu đăng nhập
    • Dùng cho môi trường development
    • Elasticsearch không config security
  2. Basic Authentication - Username/Password
    • Username: Tên đăng nhập ES (ví dụ: elastic)
    • Password: Mật khẩu ES
    • Dùng cho production environment

3.4. Elasticsearch Mapping Settings (Cấu Hình Nâng Cao)

Lưu ý: Sau khi thay đổi các cài đặt này, bạn PHẢI xóa và tạo lại index!
Setting Giá Trị Khuyến Nghị
Number of Shards 1-10 Dev: 1
Prod (<100K): 1-2
Prod (>100K): 3-5
Number of Replicas 0-5 Dev: 0
Prod (1 node): 0
Prod (2+ nodes): 1-2
Total Field Limit 1000-50000 Mặc định: 15000
Max Result Window 10000-10000000 Mặc định: 1000000
Analyzer Language english, vietnamese, thai... Tùy ngôn ngữ website

3.7. Cấu Hình Cron Job (Tùy Chọn)

Cron Job tự động đồng bộ sản phẩm theo lịch - dùng cho hệ thống lớn.

Cron Security Key
  1. Click 🔑 Generate để tạo key ngẫu nhiên
  2. Copy Cron URL
  3. Dán vào Cron service

Ví dụ URL:

https://your-site.com/wp-json/sync/es?token=abc123xyz456

Cài đặt trong cPanel Cron Jobs:

*/5 * * * * curl -X GET "https://your-site.com/wp-json/sync/es?token=YOUR_TOKEN" >/dev/null 2>&1
Lưu ý: Không chia sẻ token này công khai!

4. QUẢN LÝ SẢN PHẨM

4.1. Truy Cập Trang Quản Lý

WordPress Admin → Elastic Search → Index Product

4.2. Statistics Dashboard

Dashboard hiển thị đầy đủ thông tin về trạng thái Elasticsearch, Products, Operations và Overall Statistics.

4.3. Các Thao Tác Chính

A. Create Mapping (Tạo Mapping)
  1. Nhập Index Name (ví dụ: products)
  2. Click 📋 Create Mapping
  3. Đợi 5-10 giây
  4. Thông báo thành công
Chỉ cần làm 1 lần duy nhất! (trừ khi thay đổi mapping settings)
B. Prepare Data for Index
  1. Click 📦 Prepare Data for Index
  2. Plugin sẽ quét tất cả sản phẩm WooCommerce
  3. Thông báo: "X products have been queued for indexing"
Sản phẩm chuyển sang trạng thái Status 0 (Pending - màu xanh dương)
C. Start Indexing
  1. Nhập Batch Size (khuyến nghị: 100-500)
  2. Click ▶️ Start Indexing
  3. Theo dõi tiến trình real-time
  4. Đợi đến khi hoàn tất

Khuyến nghị Batch Size:

  • Server yếu: 50-100
  • Server trung bình: 100-300
  • Server mạnh: 300-500

6. AUTO VERIFY & SYNC

6.1. Giới Thiệu

Auto Verify & Sync là tính năng mới v1.3.7 - tự động kiểm tra và đồng bộ dữ liệu giữa Database và Elasticsearch mỗi giờ.

Chạy tự động qua cron job WordPress mỗi giờ - Không cần cấu hình gì!

6.2. Quy Trình Hoạt Động

  1. Kiểm Tra Tổng Số (Verify Total Count)
    • So sánh tổng số sản phẩm trên Database vs Elasticsearch
    • Nếu khác: tiếp tục bước 2
  2. Phát Hiện Sản Phẩm Thiếu (Find Missing Products)
    • Tìm sản phẩm tồn tại trên DB nhưng không có trên ES
    • Đánh dấu để reindex tự động
  3. Phát Hiện Sản Phẩm Thừa (Find Extra Products)
    • Tìm sản phẩm tồn tại trên ES nhưng bị xóa trên DB
    • Xóa tự động khỏi ES
  4. Sửa Sản Phẩm Lỗi (Fix Failed Products)
    • Tìm sản phẩm có status=2 (lỗi) vẫn tồn tại trên ES
    • Xóa khỏi ES để không ảnh hưởng
  5. Ghi Log (Database Logging)
    • Ghi lại tất cả hoạt động vào database
    • Xem chi tiết từ Admin → Elasticsearch → Log

6.3. Xem Nhật Ký

Truy cập WordPress Admin → Elasticsearch → Log để xem:

  • 📝 Tất cả hoạt động verify & sync
  • 🔍 Tìm kiếm theo từ khóa
  • 🏷️ Lọc theo loại log
  • 📅 Lọc theo ngày
  • ⬆️⬇️ Sắp xếp theo cột

5. ĐỒNG BỘ REAL-TIME

5.1. Giới Thiệu

Plugin tự động đồng bộ sản phẩm lên Elasticsearch khi có bất kỳ thay đổi nào.

5.2. WordPress Hooks Đã Tích Hợp

Plugin sử dụng 18 hooks để bắt mọi thay đổi:

Nhóm Hooks Mô Tả
Product CRUD save_post_product
edit_post
post_updated
wp_trash_post
untrashed_post
before_delete_post
transition_post_status 		Bắt mọi thay đổi của product
Product Meta updated_post_meta
added_post_meta
deleted_post_meta 		Price, stock, SKU...
Taxonomy set_object_terms Category/Tag/Brand
Reviews comment_post
deleted_comment
transition_comment_status 		Thêm/xóa/thay đổi review
Stock woocommerce_product_set_stock
woocommerce_variation_set_stock 		Thay đổi stock

7. WP-CLI COMMANDS

6.1. Giới Thiệu

WP-CLI cho phép index từ command line - lý tưởng cho:

  • Server operations
  • Cron jobs
  • CI/CD pipelines
  • Large-scale indexing

6.2. Index Products

Basic Usage
wp es index products
With Options
# Custom batch size (default: 100)
wp es index products --batch-size=500

# Continuous mode - process all batches until complete
wp es index products --batch-size=500 --continuous

# Force start (bỏ qua lock check)
wp es index products --force

# Combine options
wp es index products --batch-size=200 --continuous --force
Lưu ý về --continuous flag:
  • Không có flag (mặc định): Xử lý 1 batch rồi dừng → Thích hợp cho cron job gọi mỗi phút
  • Có flag --continuous: Xử lý tất cả batch cho đến hết → Thích hợp cho chạy manual một lần

6.3. Get Statistics

wp es stats

11. MÃ TRẠNG THÁI

10.1. Product Status Codes

Code Tên Màu Ý Nghĩa
0 Pending 🔵 Xanh dương Chờ đánh index
1 Success 🟢 Xanh lá Đã index thành công
2 Failed 🔴 Đỏ Index thất bại
5 Processing 🟡 Vàng Đang xử lý

📝 CHANGELOG

Version 1.3.8 (08/01/2026) - LATEST!

⚡ Performance Optimization:

  • 🚀 Cached Index Checking: Loại bỏ HEAD request chậm
    • Thêm check_index_exists() method trong PRODUCT_PR
    • Kiểm tra từ get_indices_stats() raw_data đã load
    • Giảm thời gian load: 60s → <1s (98% faster)
  • ⚡ Optimized get_status(): Không gọi ES API mỗi page load
    • Trả về field product_index_exists
    • Reuse cached data thay vì query lại
  • ✅ Smart Validation: index_data() kiểm tra mapping trước
    • Ngăn indexing khi chưa có mapping
    • Tránh lỗi "index not found"

🎨 UX Improvements:

  • ✨ Instant UI Updates: JavaScript xóa warning ngay lập tức
    • fadeOut() animation khi create mapping thành công
    • Enable 7 buttons instantly (prepare, index, reset, delete, advanced...)
    • Không reload page, chỉ AJAX refresh stats
  • 🎯 Dynamic Notice Management: Xử lý cả template và dynamic notice
    • Notice từ status-product.php template
    • Notice tạo động trong JavaScript
    • Smooth transitions với fadeOut()

🔧 Code Changes:

  • 🔒 Strict Configuration: create_mapping() yêu cầu config
    • Không còn default value 'wp_products'
    • Báo lỗi nếu chưa có configuration
  • 🧹 Code Cleanup: Xóa obsolete functions
    • Removed: has_mapping()
    • Removed: set_mapping_status()
  • 📦 Better Organization: Logic đúng chỗ
    • CONFIG_PR::get_product_config()
    • Removed JS to PHP data passing

🐛 Bug Fixes:

  • Fixed: Warning notice vẫn hiển thị sau successful mapping
  • Fixed: Dynamic notice không có ID để xóa
  • Fixed: Page load 60s do HEAD request

📝 Files Modified:

  • process/product_pr.php - Added check_index_exists(), removed obsolete methods
  • admin/product_ad.php - Uses product_index_exists field
  • admin/template-path/status-product.php - Added notice ID
  • assets/js/admin.js - Instant UI updates, remove notices
  • process/config_pr.php - Added default config values

Version 1.3.7 (28/12/2025)

✨ New Features:

  • 🔄 Auto Verify & Sync Process (VERIFY_PR Class): Tự động kiểm tra mỗi giờ
    • Auto-detect missing products - Tìm sản phẩm bị thiếu trên ES
    • Auto-detect extra products - Tìm sản phẩm thừa trên ES
    • Auto-fix failed products - Xóa sản phẩm lỗi khỏi ES
    • Comprehensive logging - Ghi log chi tiết tất cả hoạt động
  • 📊 Database Logging System (LOG_PR Class): Lưu audit trail vĩnh viễn
    • Ghi vào bảng wp_es_logs thay vì console
    • Tên log có thể cấu hình để lọc
    • Admin Log page hiển thị tất cả logs với search/filter
  • 🎯 Code Consolidation: Phương thức cha tập trung
    • is_index_enabled($type) - Kiểm tra index type
    • get_index_name($index_type) - Lấy tên index
    • Loại bỏ duplicate methods trong child classes

🔧 Improvements:

  • Configuration-driven batch sizes - Đọc từ max_rows config
  • Logging system migration - Từ CONSOLE_PR sang LOG_PR
  • Enhanced logging coverage - Ghi log tất cả verify operations
  • Vietnamese translations - Đầy đủ dịch tiếng Việt

🐛 Bug Fixes:

  • Fixed ES_SETTING undefined constant
  • Fixed get_api() deprecated calls
  • Fixed get_product_index_name() method call
  • Fixed product_db.php using get_option() directly

📝 Technical Details:

  • New VERIFY_PR class cho auto verify & sync
  • Enhanced LOG_PR class với database logging
  • Cron job chạy mỗi giờ: es_cron_auto_verify_sync
  • Log categories: verify_sync, verify_delete_extra, verify_fix_failed

Version 1.3.5 (05/12/2025)

✨ New Features:

  • 🎯 Product Configuration Section: Thêm phần cấu hình riêng cho Product
    • Tag-based input cho Indexable Post Statuses (publish, draft, pending, private...)
    • Auto-suggestion cho các WordPress post statuses phổ biến
    • Section tự động hiện/ẩn theo checkbox Product
  • 📦 CONFIG_DB Class: Class mới quản lý config tập trung
    • get_option_keys() - Lấy danh sách option keys của plugin
    • delete_all_options() - Xóa tất cả options khi uninstall
    • get/update_indexable_statuses() - Quản lý indexable statuses
    • get/set/release_indexing_lock() - Quản lý indexing lock
  • 🗑️ Uninstall Cleanup: Tự động xóa tất cả plugin options khi uninstall
    • es_setting, es_indexable_statuses
    • es_logs_per_page, es_indexing_lock, es_stop_indexing

🔧 Improvements:

  • Product count now respects configured indexable statuses
  • Moved get_indexable_statuses() to PRODUCT_DB class
  • Added i18n strings for Product Configuration section

🐛 Bug Fixes:

  • Fixed product count mismatch - chỉ đếm products với configured statuses
  • Fixed missing cleanup of plugin options on uninstall

Version 1.3.2 (01/12/2025)

✨ New Features:

  • 📝 Log Admin Page Redesign: Complete UI overhaul matching Product Admin style
  • 🗑️ Delete All Logs Confirmation: Custom showConfirm() popup dialog

🐛 Bug Fixes:

  • Fixed HTML nested forms error in Log Admin
  • Fixed Log Admin page not loading CSS/FontAwesome icons
  • Fixed count_product() total calculation

Version 1.3.0 (28/11/2025)

🔥 Major Changes:

  • 🚀 OPTIMIZED HOOKS: Giảm từ 32 hooks xuống 16 hooks không trùng lặp
    • Loại bỏ các hooks redundant (edit_post, post_updated, woocommerce_new_product, etc.)
    • Tăng hiệu năng, giảm overhead khi save product
  • ✨ ES DELETE HANDLING: Xử lý xóa sản phẩm khỏi Elasticsearch
    • action='deleted' → Xóa document khỏi ES (product bị xóa vĩnh viễn)
    • action='trashed' → Re-index với post_status='trash'
    • Priority system: 'deleted' action không bị override
  • 🔄 AUTO RESET STUCK: Tự động reset cả index stuck và delete stuck
    • Status 5 → Status 0 sau 5 phút
    • Status 7 → Status 6 sau 5 phút

New Features:

  • ✅ process_realtime_delete() - Xử lý xóa realtime qua ES API
  • ✅ mark_products_for_delete_batch() - Queue mode delete
  • ✅ mark_products_processing_delete() - Realtime mode delete
  • ✅ Separate tracking cho index vs delete operations
  • ✅ Added product_shipping_class taxonomy support

Improvements:

  • 🎯 Simplified es_sync_product() function với Vietnamese comments
  • 🎯 Trigger merging khi cùng 1 product trigger nhiều hooks trong 1 request
  • 🎯 Better logging với trigger count display
  • 🎯 Variation stock changes now sync parent product

Status Codes Updated:

Code Name Description
0 pending_index Chờ đánh index
1 index_success Index thành công
2 index_failed Index thất bại
5 processing_index Đang xử lý index
6 pending_delete Chờ xóa khỏi ES
7 processing_delete Đang xử lý xóa
8 delete_success Xóa thành công
9 delete_failed Xóa thất bại

Version 1.2.1 (20/11/2025)

Improvements:

  • 🚀 Simplified Analyzer Language - now defaults to English (removed from UI)
  • 🌐 Full multilingual support for CLI commands using __() function
  • 🎯 Removed --max-batches parameter from CLI (simplified usage)
  • 🔄 Added --continuous flag for CLI: single batch for cron, continuous for manual
  • 🐛 Fixed continuous flag logic check in batch processing loop
  • 📝 Updated CLI messages: "Logging to database" → "Saving logs to database"
  • 🔧 Improved CLI command workflow for better cron job compatibility

Breaking Changes:

  • ⚠️ Analyzer Language setting removed from Config UI (hardcoded to 'english')
  • ⚠️ --max-batches CLI parameter removed (use --continuous flag instead)

Version 1.2.0 (19/11/2025)

New Features:

  • ✨ Console Monitor with real-time logs
  • ✨ 18 WordPress hooks for auto-sync
  • ✨ WP-CLI commands support
  • ✨ Advanced mapping settings (shards, replicas, field limit)
  • ✨ Analyzer language configuration
  • ✨ Reindex all/failed products buttons
  • ✨ Force clear lock mechanism
  • ✨ Batch sync at shutdown hook

Improvements:

  • 🚀 Optimized database queries
  • 🚀 Better bulk indexing performance
  • 🚀 Lock mechanism to prevent conflicts
  • 🚀 Auto-reset stuck products (5 min)
  • 🚀 Auto-cleanup old logs (7 days)

Bug Fixes:

  • 🐛 Fixed nested mapping for taxonomies
  • 🐛 Fixed memory issues with large batches
  • 🐛 Fixed lock not releasing on error
  • 🐛 Fixed console logs encoding

Developer:

  • 🔧 Added 10+ action/filter hooks
  • 🔧 Comprehensive hook documentation
  • 🔧 Example code snippets

Version 1.1.9 (14/10/2025)

Initial release

📄 LICENSE

GPL-2.0 License

Copyright (C) 2025 Aboyit

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

🎉 Cảm ơn bạn đã sử dụng WP Elasticsearch!