FUNCTION_REGISTRY.md — thegioikeycap.vn
Registry các hàm và class quan trọng đã tồn tại.
Kiểm tra file này trước khi viết bất kỳ hàm mới nào.
Quy ước: hàm toàn cục prefix tgk_, class prefix TGK_.
Cấu hình site
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_site() |
function |
inc/site-config.php |
Source of truth thông tin shop. tgk_site('phone'), tgk_site() trả cả mảng |
Mọi chỗ cần SĐT, địa chỉ, mạng xã hội, ngưỡng freeship. Đừng hardcode |
tgk_tel() |
function |
inc/site-config.php |
SĐT dạng href="tel:" (bỏ khoảng trắng) |
Link gọi điện |
tgk_messenger_url() |
function |
inc/site-config.php |
URL chat Messenger trực tiếp (https://m.me/thegioikeycap) |
Nút chat Messenger nổi, header, footer, PDP |
tgk_fb_handle() |
function |
inc/site-config.php |
Handle Facebook (phần sau facebook.com/) |
Hiện link rút gọn trên topbar |
tgk_logo_url() |
function |
inc/site-config.php |
URL logo — ưu tiên custom_logo của WP, fallback asset theme |
Header, footer, email |
tgk_placeholder_url() |
function |
inc/site-config.php |
Ảnh thay thế khi sản phẩm/danh mục không có hình |
Mọi chỗ in ảnh sản phẩm |
Helper dùng chung
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_icon( $name, $size ) |
function |
inc/helpers.php |
Trả về SVG inline theo tên |
Cần chuỗi icon để ghép chuỗi |
tgk_the_icon( $name, $size ) |
function |
inc/helpers.php |
In icon ra thẳng |
Trong template |
tgk_data( $file ) |
function |
inc/helpers.php |
Đọc JSON trong data/, cache theo request |
Đọc vn-provinces.json, category-meta.json… Đừng file_get_contents tay |
tgk_breadcrumb( array $items ) |
function |
inc/helpers.php |
In breadcrumb (JSON-LD kèm ở inc/seo.php) |
Mọi trang cần breadcrumb |
tgk_product_categories( $limit ) |
function |
inc/helpers.php |
Danh mục có sản phẩm, sắp theo số lượng giảm dần |
Menu, footer, trang chủ |
Khởi tạo & permalink
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_content_uses_blocks() |
function |
functions.php |
Nội dung có dùng block không — quyết định có nạp CSS block |
Trước khi enqueue asset của block editor |
tgk_setup_permalinks() |
function |
functions.php |
Giữ /{slug}/ cho product, product_cat và post |
⚠️ Không đổi — vỡ SEO/backlink của bản Astro cũ |
tgk_setup_pages() |
function |
functions.php |
Tạo/giữ trang mặc định đúng URL cũ: /san-pham/ /gio-hang/ /thanh-toan/ /tai-khoan/ /tin-tuc/ /test-ban-phim/ |
Chạy tự động; sửa khi thêm trang hệ thống |
Điều hướng
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_default_nav() |
function |
inc/nav.php |
Cấu trúc menu mặc định khi admin chưa gán menu |
Sửa menu mặc định |
tgk_render_primary_nav() |
function |
inc/nav.php |
In menu chính |
header.php |
tgk_footer_product_links() |
function |
inc/nav.php |
Link danh mục sản phẩm ở chân trang |
footer.php |
Tài khoản & xác thực
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_login_url() / tgk_register_url() / tgk_registered_url() |
function |
inc/account.php |
URL các trang tài khoản |
Mọi link tới đăng nhập/đăng ký. Đừng hardcode đường dẫn |
tgk_pending_email( $set ) |
function |
inc/account.php |
Đọc/ghi email đang chờ xác thực |
Luồng xác thực email |
tgk_is_verified( $user_id ) |
function |
inc/account.php |
Tài khoản đã xác thực email chưa |
Gate chức năng theo trạng thái xác thực |
tgk_mark_verified( $user_id ) |
function |
inc/account.php |
Đánh dấu đã xác thực |
Handler link kích hoạt |
tgk_needs_password( $user_id ) |
function |
inc/account.php |
User đăng nhập bằng Google mà chưa đặt mật khẩu |
Quyết định có hiện panel mời đặt mật khẩu |
tgk_social_buttons( $type ) |
function |
inc/account.php |
In nút đăng nhập mạng xã hội |
⚠️ Phải gọi trực tiếp. Hook của Nextend chỉ đăng ký lại login_form/register_form, mà template WooCommerce không bao giờ bắn hai action đó → plugin nạp đủ CSS/JS nhưng không hiện nút nào |
tgk_password_panel() |
function |
inc/account.php |
Panel mời đặt mật khẩu cho khách đăng nhập Google |
Trang tài khoản |
tgk_send_verification_email( $user_id ) |
function |
inc/account.php |
Gửi email kích hoạt |
Sau đăng ký, khi gửi lại |
tgk_password_rules() |
function |
inc/account.php |
Một nguồn duy nhất cho quy tắc mật khẩu |
Dùng cho cả kiểm tra server và checklist trên màn hình — để hai bên không lệch nhau |
tgk_password_failures( $password ) |
function |
inc/account.php |
Quy tắc nào chưa đạt |
Validate + hiện lỗi |
tgk_notice( $message, $type ) |
function |
inc/account.php |
Thêm thông báo, ép mở session trước |
⚠️ Dùng thay wc_add_notice() ở luồng ngoài WooCommerce, nếu không khách bấm link hỏng sẽ thấy trang trơn không lời giải thích |
CAPTCHA (Cloudflare Turnstile)
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_captcha_enabled() |
function |
inc/captcha.php |
Đã cấu hình đủ key chưa |
Gate mọi thứ liên quan CAPTCHA |
tgk_captcha_field() |
function |
inc/captcha.php |
In widget. Gọi trực tiếp trong template, ngay TRÊN nút submit |
⚠️ Script nạp tại chỗ chứ không enqueue toàn site — chỉ 3 trang cần |
tgk_captcha_verify() |
function |
inc/captcha.php |
Kiểm tra token với Cloudflare |
Mọi handler form có CAPTCHA |
tgk_captcha_ip() |
function |
inc/captcha.php |
IP thật của khách |
Gửi kèm khi siteverify |
Hành vi đã chốt: lỗi mạng hoặc sai cấu hình thì cho qua (không chặn khách mua
hàng vì Cloudflare down); timeout-or-duplicate thì chặn kèm lời nhắn dễ hiểu.
WooCommerce
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_category_seo_box() |
function |
inc/woocommerce.php |
In mô tả danh mục ở CUỐI trang |
⚠️ Cố ý đặt cuối: mô tả dài 20.000+ ký tự, để đầu thì khách phải cuộn qua cả bài mới thấy sản phẩm |
tgk_cart_badge() |
function |
inc/woocommerce.php |
Badge số lượng trên icon giỏ |
Header (có fragment AJAX) |
tgk_thankyou_upsell( $order ) |
function |
inc/woocommerce.php |
Gợi ý sản phẩm ở trang cảm ơn |
⚠️ Luôn loại thứ khách vừa mua, và chỉ lấy hàng còn trong kho |
tgk_checkout_coupon_box() |
function |
inc/checkout.php |
Ô nhập mã giảm giá ở trang thanh toán (áp bằng AJAX) |
Đã móc sẵn dưới bảng đơn hàng |
Thông báo WooCommerce
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_notice_muted_types() |
function |
inc/notices.php |
Loại thông báo đang tắt. Mặc định ['success','notice'] |
⚠️ error cố ý KHÔNG tắt — đó là cách khách biết vì sao không đặt được hàng |
tgk_notice_allowlist() |
function |
inc/notices.php |
★ Bật lại một thông báo cụ thể: thêm một mẩu chữ đặc trưng của nó vào đây (khớp chuỗi con, không phân biệt hoa thường) |
Chỗ DUY NHẤT cần sửa khi chủ shop muốn hiện lại một thông báo |
tgk_notices_visible( $notices, $type ) |
function |
inc/notices.php |
Lọc danh sách trước khi in; cũng bỏ mục rỗng |
3 template woocommerce/notices/*.php gọi. Đừng gọi nơi khác |
Có 2 filter để chỉnh từ ngoài: tgk_notice_muted_types, tgk_notice_allowlist.
Email
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_email_html( $heading, $body ) |
function |
inc/emails.php |
Khung HTML dùng chung cho mọi email |
Mọi email tự viết. Đừng dựng HTML tay |
tgk_send_html_email( $to, $subject, $heading, $body ) |
function |
inc/emails.php |
Gửi luôn, bọc sẵn khung |
Khi ta chủ động gửi |
tgk_email_order_no( $order ) |
function |
inc/emails.php |
Số đơn để hiển thị |
Tiêu đề và nội dung email đơn hàng |
tgk_sysmail_ready() |
function |
inc/emails-system.php |
Điều kiện đủ để thay email hệ thống |
Gate |
tgk_sysmail_name( WP_User $user ) |
function |
inc/emails-system.php |
Tên hiển thị của khách |
Xưng hô trong email |
tgk_sysmail_security_footer() |
function |
inc/emails-system.php |
Chân thư cảnh báo bảo mật |
Email đổi mật khẩu / đổi email |
tgk_stock_email_body( $product, $headline, $extra ) |
function |
inc/emails-system.php |
Nội dung 3 email tồn kho |
Email báo hết hàng / sắp hết |
⚠️ Mỗi filter đổi nội dung email HTML đều phải đi kèm một filter header đặt
Content-Type: text/html, nếu không khách nhận được mã HTML thô.
SEO
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_blog_to_category() |
function |
inc/seo.php |
Bảng 301 bài viết cũ → danh mục. Chỉ gồm bài đúng chủ đề danh mục đích |
Thêm redirect mới |
tgk_category_meta( $slug ) |
function |
inc/seo.php |
Meta title/description đã soạn cho 1 danh mục |
Đọc từ data/category-meta.json |
tgk_current_category_meta() |
function |
inc/seo.php |
Meta của danh mục đang xem |
Template archive |
tgk_redirected_post_ids() |
function |
inc/seo.php |
ID các bài đã 301 đi |
Loại khỏi sitemap, khỏi danh sách bài viết |
tgk_utility_page_ids() |
function |
inc/seo.php |
ID trang tiện ích (giỏ hàng, thanh toán, tài khoản) |
Đặt noindex |
Nội dung danh mục
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_category_description_html() |
function |
inc/category-content.php |
Mô tả danh mục đã lọc, sẵn sàng in |
Mọi chỗ hiện mô tả danh mục |
tgk_category_has_real_content() |
function |
inc/category-content.php |
Có ≥ TGK_INDEX_MIN_CHARS (300) ký tự chữ không |
Quyết định index / vào sitemap |
⚠️ Bẫy kses: file này nới bộ thẻ cho pre_term_description và
term_description lên cấp bài viết. Gỡ đoạn đó ra là lần lưu danh mục kế tiếp
xoá sạch nội dung, không báo lỗi gì. Xem docs/SEO_CONTENT.md.
Vận chuyển — Bảng giá SPX theo cân nặng (AllinGo)
| Name |
Type |
File |
Purpose |
When to reuse |
tgk_allingo_token() |
function |
inc/shipping.php |
Lấy OAuth token AllinGo Live, có cache |
Dùng trong script đối soát cước hoặc tính năng quản trị |
tgk_allingo_quotes( $dropoff, $package, $cod ) |
function |
inc/shipping.php |
Gọi POST /inquiries lấy báo giá qua ví wallet |
Script đối soát cước |
tgk_allingo_origin() |
function |
inc/shipping.php |
Điểm gửi hàng (Thủ Đức, TP.HCM, 3 cấp chuẩn) |
Dựng payload AllinGo |
tgk_allingo_cart_weight( array $contents ) |
function |
inc/shipping.php |
Tổng cân nặng giỏ. Coi <= 0 là chưa khai (mặc định 0,5 kg) |
Tính cước vận chuyển |
TGK_Shipping_Allingo |
class |
inc/shipping.php |
WC_Shipping_Method id tgk_allingo. Tính cước SPX theo cân nặng nội bộ, không gọi API ngoài lúc checkout |
Đăng ký vào shipping zone |
Plugin tgk-tracking
| Name |
Type |
File |
Purpose |
When to reuse |
TGK_Events::content_id() |
static method |
class-events.php |
Content ID gửi Meta = SKU, fallback về ID sản phẩm |
⚠️ Mọi event. Phải khớp catalog Pancake đẩy lên, nếu không conversion không match sản phẩm |
TGK_Events::content_id_by() |
static method |
class-events.php |
Content ID theo id truyền vào |
Dòng sản phẩm trong đơn |
TGK_Events::should_track() |
static method |
class-events.php |
Có bắn event không |
⚠️ Lọc bot ở đây. curl và headless Chrome mặc định bị coi là bot — khi debug phải đổi User-Agent, nếu không sẽ tưởng pixel hỏng |
TGK_Events::is_bot() |
static method |
class-events.php |
Nhận diện bot |
|
TGK_Events::utm_params() |
static method |
class-events.php |
Đọc UTM từ URL/session |
Ghi nguồn đơn |
TGK_Events::capture_order_attribution() |
static method |
class-events.php |
Lưu UTM + _fbp/_fbc vào đơn |
Chạy khi tạo đơn |
TGK_User_Data::build() / from_order() / from_current_user() |
static method |
class-user-data.php |
Dựng khối user data cho CAPI |
Mọi event server |
TGK_User_Data::hash() / hash_email() / hash_phone() |
static method |
class-user-data.php |
Chuẩn hoá + SHA-256 theo đúng chuẩn Meta |
Mọi PII. Đừng tự hash |
TGK_User_Data::fbp() |
static method |
class-user-data.php |
Sinh fb.1.{ms}.{rand} và set cookie first-party 90 ngày |
Khi pixel bị chặn — nhờ vậy vẫn có định danh trình duyệt |
TGK_User_Data::fbc() |
static method |
class-user-data.php |
Đọc _fbc từ cookie hoặc fbclid |
|
TGK_User_Data::client_ip() |
static method |
class-user-data.php |
IP thật sau proxy |
|
TGK_Event_ID::purchase() / registration() / initiate_checkout() / add_to_cart() / page_view() |
static method |
class-event-id.php |
Sinh event_id tất định |
⚠️ Cốt lõi chống trùng: client và server phải ra cùng một chuỗi cho cùng một hành động |
TGK_CAPI::send() |
static method |
class-capi.php |
Gọi Conversions API |
Gửi event server |
TGK_Queue::schedule() / dispatch() / dispatch_now() |
static method |
class-queue.php |
Hàng đợi gửi CAPI qua cron |
Gửi không chặn request |
TGK_Pixel::base_code() / events() |
static method |
class-pixel.php |
In pixel + hàng đợi client |
|
TGK_Rest::handle() |
static method |
class-rest.php |
Nhận báo cáo "client đã bắn" |
⚠️ Payload dùng key event_name, không phải name |
TGK_Config |
class |
class-config.php |
Đọc hằng số TGK_* từ wp-config.php |
Mọi chỗ cần cấu hình |
TGK_Store |
class |
class-store.php |
Lưu event vào DB để đối chiếu |
Debug, báo cáo |
TGK_Admin::order_source_box() |
static method |
class-admin.php |
Metabox "Nguồn đơn hàng" (UTM + trạng thái _fbp/_fbc) |
⚠️ Screen id phải xử lý cả HPOS lẫn post cũ |
Do Not Duplicate
Trước khi viết bất kỳ thứ nào dưới đây, dùng cái đã có:
| Định viết |
Đã có |
| Đọc thông tin shop |
tgk_site() |
Đọc file JSON trong data/ |
tgk_data() |
| Dựng HTML email |
tgk_email_html() |
| Hash PII cho Meta |
TGK_User_Data::hash*() |
| Sinh event_id |
TGK_Event_ID::* |
| Xác định Content ID |
TGK_Events::content_id() |
| Kiểm tra quy tắc mật khẩu |
tgk_password_rules() / tgk_password_failures() |
| Kiểm tra CAPTCHA |
tgk_captcha_verify() |
| Lấy IP thật của khách |
TGK_User_Data::client_ip() hoặc tgk_captcha_ip() |