Hướng dẫn xây dựng hệ thống cập nhật theme WordPress

Bài viết này hướng dẫn cách triển khai hệ thống update theme hoàn chỉnh, sử dụng Init Press làm ví dụ thực tế, dựa trên site_transient_update_themes.

Tổng quan kiến trúc hệ thống update theme

Một hệ thống update theme thủ công thường gồm 3 thành phần chính:

• Theme cài trên website người dùng
• Một file JSON công khai chứa thông tin phiên bản
• Một file ZIP chứa bản theme mới nhất

WordPress sẽ định kỳ gọi filter site_transient_update_themes, tại đây theme có thể tự đăng ký thông tin cập nhật nếu phát hiện phiên bản mới.

Cấu trúc file JSON phiên bản

File JSON đóng vai trò như “API version”, cần được public và trả về thông tin tối thiểu để WordPress so sánh phiên bản.

{
    "name": "Init Press",
    "slug": "init-press",
    "version": "1.1.0",
    "author": "Init HTML",
    "homepage": "https://inithtml.com/theme/init-press/",
    "description": "A clean, lightweight, and UIkit-powered WordPress theme for blogs, content sites, and modern publications.",
    "requires": "6.3",
    "tested": "6.9",
    "requires_php": "7.4"
}

Trong đó, version là trường quan trọng nhất, được dùng để so sánh với phiên bản đang cài.

Hook vào hệ thống update của WordPress

Toàn bộ logic cập nhật được đặt trong khu vực admin để tránh ảnh hưởng frontend. Filter site_transient_update_themes cho phép chèn dữ liệu update trực tiếp vào core update checker của WordPress.

/**
 * Theme updater
 */
if ( is_admin() ) {
    add_filter( 'site_transient_update_themes', function ( $transient ) {
        $theme_slug  = 'init-press'; // folder theme
        $theme       = wp_get_theme( $theme_slug );

        if ( ! $theme->exists() ) {
            return $transient;
        }

        $current_ver = $theme->get( 'Version' );

        // JSON chứa thông tin version
        $json_url = 'https://inithtml.com/releases/themes/init-press.json?nocache=' . time();

        $res = wp_remote_get( $json_url, [
            'timeout' => 10,
        ]);

        if ( is_wp_error( $res ) || wp_remote_retrieve_response_code( $res ) !== 200 ) {
            return $transient;
        }

        $info = json_decode( wp_remote_retrieve_body( $res ) );

        if ( ! $info || empty( $info->version ) ) {
            return $transient;
        }

        if ( version_compare( $info->version, $current_ver, '>' ) ) {

            if ( ! is_object( $transient ) ) {
                $transient = new stdClass();
            }

            $transient->response[ $theme_slug ] = [
                'theme'       => $theme_slug,
                'new_version' => $info->version,
                'url'         => $info->homepage ?? '',
                'package'     => 'https://inithtml.com/releases/themes/init-press.zip?ver=' . $info->version,
            ];
        }

        return $transient;
    });
}

Giải thích luồng xử lý

• Lấy thông tin theme hiện tại bằng wp_get_theme()
• Đọc version đang cài từ style.css
• Gửi HTTP request đến file JSON phiên bản
• So sánh version bằng version_compare()
• Đăng ký bản update vào $transient->response

Khi WordPress hiển thị trang Updates, hệ thống sẽ tự động nhận diện và cho phép cập nhật theme như theme chính thống.

Ý nghĩa các field trong response update

• theme: slug thư mục theme
• new_version: phiên bản mới nhất
• url: trang giới thiệu theme
• package: link ZIP dùng để update

File ZIP phải chứa đúng cấu trúc theme, thư mục gốc trùng với theme_slug.

Một số lưu ý quan trọng khi triển khai thực tế

• Nên bật cache phía server cho file JSON để giảm tải
• Có thể thêm token hoặc chữ ký để bảo vệ link ZIP
• Không nên đặt logic update ở frontend
• Luôn test update trên site staging trước khi phát hành

Kết luận

Hệ thống custom theme updater giúp theme WordPress ngoài WordPress.org vẫn có trải nghiệm cập nhật chuyên nghiệp, liền mạch và an toàn. Với cách tiếp cận dựa trên site_transient_update_themes, việc triển khai tương đối gọn gàng, dễ kiểm soát và phù hợp cho các sản phẩm theme thương mại hoặc nội bộ.

Đây là nền tảng quan trọng cho mọi hệ sinh thái theme WordPress phát hành độc lập, đặc biệt khi cần kiểm soát version, phân phối và vòng đời sản phẩm.