Quản lý bộ đệm: Hệ thống bộ đệm dựa trên móc dành cho nhà phát triển

Last updated on Jun 24, 2026 02:02

PolyCMS cung cấp hệ thống Quản lý bộ nhớ đệm tập trung cung cấp cho quản trị viên giao diện người dùng để kiểm tra và xóa bộ nhớ đệm - đồng thời cung cấp cho các nhà phát triển API điều khiển móc mạnh mẽ để tích hợp logic bộ nhớ đệm của riêng họ mà không xung đột với lõi hoặc các mô-đun khác.

Hướng dẫn này bao gồm kiến trúc, các hook có sẵn và các ví dụ thực tế dành cho các nhà phát triển mô-đun và chủ đề muốn mở rộng, thay thế hoặc phản ứng với các hoạt động của bộ nhớ đệm.

Tổng quan về kiến trúc

CacheService (app/Services/CacheService.php) là điểm truy cập duy nhất cho tất cả các hoạt động của bộ đệm. Nó duy trì một sổ đăng ký các loại bộ đệm được nhóm thành bốn loại:

Nhóm	Mô tả	Các loại tích hợp
`laravel`	bộ đệm khung Laravel	Ứng dụng, Xem, Cấu hình, Lộ trình, Sự kiện
`polycms`	Bộ đệm dịch vụ nội bộ PolyCMS	Chủ đề, Mô-đun, Cài đặt, Trình giải quyết mẫu
`server`	Bộ đệm cấp máy chủ	Bộ đệm PHP
`module`	Bộ đệm đã đăng ký mô-đun	(Mô-đun của bạn thêm vào đây)

Hệ thống hiển thị 7 hook và bộ lọc mà các mô-đun có thể sử dụng để tham gia quản lý bộ đệm.

Tham khảo móc & bộ lọc

Bộ lọc (Bộ biến đổi giá trị)

Những hook này cho phép các module sửa đổi dữ liệu trước khi nó được sử dụng.

`cache.types` — Đăng ký các loại bộ đệm tùy chỉnh

Thêm các loại bộ đệm của riêng bạn vào hệ thống. Loại của bạn sẽ xuất hiện trong trang Quản lý bộ đệm của quản trị viên cùng với các loại cốt lõi.

Chữ ký: mảng $types

use App\Facades\Hook;

Hook::addFilter('cache.types', function (array $types) {
    $types[] = [
        'key'         => 'cdn_purge',
        'label'       => 'CDN Cache',
        'description' => 'Purge Cloudflare or Fastly edge cache',
        'group'       => 'module',   // Use 'module' for custom types
        'clearable'   => true,
    ];
    return $types;
});

Các trường bắt buộc cho mỗi loại:

Lĩnh vực	Loại	Mô tả
`key`	`string`	Sên duy nhất (được sử dụng trong lệnh gọi API)
`label`	`string`	Tên con người có thể đọc được
`description`	`string`	Giải thích ngắn gọn hiển thị trong giao diện người dùng quản trị viên
`group`	`string`	`laravel`, `polycms`, `server`, hoặc `module`
`clearable`	`bool`	Nút "Xóa" có xuất hiện hay không

`cache.type.handler` — Yêu cầu quyền sở hữu loại bộ đệm

Đây là cơ chế ngăn ngừa xung đột. Khi một mô-đun xác nhận một loại bộ đệm, lõi sẽ bỏ qua logic xóa của chính nó cho loại đó và ủy quyền hoàn toàn cho hook hành động cache.clear.{type} của mô-đun.

Chữ ký: ?string $handler, string $type

Trường hợp sử dụng: Bạn đang xây dựng một mô-đun quản lý Redis chuyên dụng và muốn xử lý bộ nhớ đệm ứng dụng khác với bộ nhớ đệm ``php Artisan cache:clear` mặc định.

Hook::addFilter('cache.type.handler', function (?string $handler, string $type) {
    if ($type === 'application') {
        return 'RedisManager'; // Your module name — core skips its clear logic
    }
    return $handler; // Return null for types you don't handle
}, 10, 2);

Khi trình xử lý được đặt, giao diện người dùng quản trị sẽ hiển thị huy hiệu cho biết mô-đun nào quản lý loại bộ đệm đó.

`cache.status` — Làm phong phú dữ liệu trạng thái

Thêm số liệu hoặc chẩn đoán tùy chỉnh vào phản hồi trạng thái bộ đệm.

Chữ ký: mảng $status

Hook::addFilter('cache.status', function (array $status) {
    // Add Redis memory info to the status payload
    $status['redis_info'] = [
        'used_memory_mb' => Redis::info()['used_memory_human'] ?? 'N/A',
        'connected_clients' => Redis::info()['connected_clients'] ?? 0,
    ];
    return $status;
});

Hành động (Gọi lại sự kiện)

Những cái móc này kích hoạt tại các điểm vòng đời cụ thể. Họ không trả lại giá trị.

`cache.clearing` — Trước khi một loại bị xóa

Kích hoạt ngay lập tức trước khi bất kỳ loại bộ đệm nào bị xóa. Sử dụng để ghi nhật ký hoặc xóa ảnh chụp nhanh trước.

Chữ ký: chuỗi $type

Hook::addAction('cache.clearing', function (string $type) {
    Log::info("Cache clear starting: {$type}");
});

`cache.clear.{type}` — Xử lý việc xóa cho một loại cụ thể

Đây là điểm mấu chốt để triển khai logic thanh toán bù trừ của riêng bạn. Nếu mô-đun của bạn đã xác nhận một loại thông qua cache.type.handler, thì đây là nơi công việc thực tế diễn ra.

Chữ ký: void

// Handle clearing for your custom CDN cache type
Hook::addAction('cache.clear.cdn_purge', function () {
    CloudflareApi::purgeEverything(config('services.cloudflare.zone_id'));
});

// Or override the core's application cache clearing
Hook::addAction('cache.clear.application', function () {
    Redis::connection('cache')->flushdb();
});

`cache.cleared` — Sau khi một loại bị xóa

Kích hoạt sau khi loại bộ đệm đã bị xóa (hoặc đã thử) với cờ thành công.

Chữ ký: string $type, bool $success

Hook::addAction('cache.cleared', function (string $type, bool $success) {
    if ($success) {
        Log::info("Cache cleared successfully: {$type}");
    } else {
        Log::warning("Cache clear failed: {$type}");
    }
}, 10, 2);

`cache.clear_all.trước` / `cache.clear_all.after`

Kích hoạt trước và sau thao tác xóa hàng loạt (khi quản trị viên nhấp vào "Xóa tất cả bộ nhớ đệm").

Hook::addAction('cache.clear_all.before', function (array $types) {
    // $types = ['application', 'view', 'config', 'route', 'event', ...]
    Log::info('Bulk cache clear starting for: ' . implode(', ', $types));
});

Hook::addAction('cache.clear_all.after', function (array $results) {
    // $results = ['application' => 'success', 'view' => 'success', ...]
    $failed = array_filter($results, fn($r) => $r !== 'success');
    if (empty($failed)) {
        Log::info('All caches cleared successfully');
    }
});

Điểm cuối API REST

Hệ thống quản lý bộ đệm hiển thị hai điểm cuối API được xác thực:

`NHẬN /api/v1/system/cache/status`

Trả về trạng thái hiện tại của tất cả các loại bộ đệm đã đăng ký.

Phản ứng:

{
  "data": {
    "driver": "file",
    "store": "file",
    "types": [
      {
        "key": "application",
        "label": "Application Cache",
        "description": "General key-value cache store",
        "group": "laravel",
        "clearable": true,
        "handler": null,
        "info": { "driver": "file" }
      },
      {
        "key": "view",
        "label": "View Cache",
        "group": "laravel",
        "clearable": true,
        "handler": null,
        "info": { "compiled_count": 75 }
      }
    ]
  }
}

`POST /api/v1/system/cache/clear`

Xóa một hoặc nhiều loại bộ đệm.

Nội dung yêu cầu:

{
  "types": ["view", "config", "theme"]
}

Hoặc xóa mọi thứ:

{
  "types": ["all"]
}

Phản ứng:

{
  "success": true,
  "results": {
    "view": "success",
    "config": "success",
    "theme": "success"
  },
  "message": "All selected caches cleared successfully."
}

Ví dụ thực tế

Ví dụ 1: Mô-đun thanh lọc CDN

Một mô-đun hoàn chỉnh đăng ký loại bộ đệm CDN và xử lý việc xóa nó:

// In your module's ServiceProvider boot() method

use App\Facades\Hook;

public function boot(): void
{
    // Register the cache type
    Hook::addFilter('cache.types', function (array $types) {
        $types[] = [
            'key'         => 'cdn',
            'label'       => 'CDN Edge Cache',
            'description' => 'Purge Cloudflare edge cache for all zones',
            'group'       => 'module',
            'clearable'   => true,
        ];
        return $types;
    });

    // Handle clearing
    Hook::addAction('cache.clear.cdn', function () {
        $zoneId = config('services.cloudflare.zone_id');
        $apiToken = config('services.cloudflare.api_token');

        Http::withToken($apiToken)
            ->post("https://api.cloudflare.com/client/v4/zones/{$zoneId}/purge_cache", [
                'purge_everything' => true,
            ]);
    });
}

Ví dụ 2: Full-Page Cache Module (Chiếm lấy Core)

Một mô-đun thay thế trình xử lý bộ đệm ứng dụng mặc định bằng giải pháp dựa trên Varnish:

public function boot(): void
{
    // Claim the 'application' cache type
    Hook::addFilter('cache.type.handler', function (?string $handler, string $type) {
        if ($type === 'application') {
            return 'VarnishCache';
        }
        return $handler;
    }, 10, 2);

    // Provide custom clearing logic
    Hook::addAction('cache.clear.application', function () {
        // Ban all objects from Varnish
        Http::withHeaders(['X-Purge' => '.*'])
            ->request('BAN', config('services.varnish.host'));

        // Also clear Laravel's cache store
        Artisan::call('cache:clear');
    });
}

Ví dụ 3: Chức năng chủ đề — Tự động xóa khi lưu cài đặt

Một chủ đề xóa nội dung đã biên dịch của chính nó khi Tùy chọn chủ đề được lưu:

// In themes/my-theme/functions.php

Hook::addAction('cache.cleared', function (string $type, bool $success) {
    if ($type === 'theme' && $success) {
        // Regenerate compiled theme CSS
        $css = MyTheme::compileStyles();
        file_put_contents(public_path('themes/my-theme/compiled.css'), $css);
    }
}, 10, 2);

Tự động xóa khi tải lên chủ đề

Khi một chủ đề được tải lên hoặc cập nhật thông qua bảng quản trị, PolyCMS sẽ tự động xóa các bộ đệm sau:

Xem bộ đệm — Xóa các mẫu Blade đã biên dịch cũ

Config Cache — Đảm bảo tải các định nghĩa cài đặt functions.php mới

OPcache — Xóa bộ đệm mã byte PHP để các tệp PHP mới được biên dịch mới

Bộ đệm chủ đề — Xóa sổ đăng ký nội bộ của Trình quản lý chủ đề

Bộ đệm cài đặt — Tải lại cài đặt tự động tải (bao gồm Tùy chọn chủ đề mới)

Bộ nhớ đệm mẫu — Làm mới độ phân giải đường dẫn chế độ xem của Trình phân giải mẫu

Điều này giúp loại bỏ sự cố phổ biến khiến Tùy chọn chủ đề hoặc chế độ xem mới không xuất hiện sau khi cập nhật chủ đề.

Giao diện người dùng quản trị

Bạn có thể truy cập trang Quản lý bộ đệm tại Trung tâm cài đặt → Hệ thống → Bộ đệm (hoặc trực tiếp tại /admin/settings/cache). Nó cung cấp:

Thông tin trình điều khiển bộ đệm ở trên cùng (tệp, cơ sở dữ liệu, redis, v.v.)

Thẻ loại bộ đệm được nhóm được tổ chức bởi Laravel, PolyCMS, Máy chủ và Mô-đun

Huy hiệu trạng thái hiển thị số lượt xem đã tổng hợp, trạng thái được lưu vào bộ nhớ đệm/không được lưu vào bộ nhớ đệm, tỷ lệ trúng OPcache

Các nút xóa riêng lẻ cho mỗi loại bộ đệm có trạng thái tải

"Xóa tất cả bộ nhớ đệm" nút chính

Huy hiệu người xử lý hiển thị mô-đun nào quản lý một loại cụ thể

Hỗ trợ đầy đủ chế độ tối

Các phương pháp hay nhất

Sử dụng cache.type.handler để ngăn chặn xung đột. Nếu mô-đun của bạn tiếp quản loại bộ đệm, hãy luôn đăng ký trình xử lý để lõi và các mô-đun khác biết rằng không can thiệp.

Giữ trình xử lý cache.clear.{type} nhanh chóng. Quản trị viên mong muốn việc xóa bộ nhớ đệm sẽ gần như ngay lập tức. Đối với các hoạt động chậm (chẳng hạn như thanh lọc CDN), hãy cân nhắc xếp hàng công việc và quay lại ngay lập tức.

Luôn trả về $handler trong chuỗi bộ lọc. Nếu bạn đang kiểm tra cache.type.handler để tìm một loại cụ thể, hãy luôn trả về $handler ban đầu cho những loại bạn không quản lý.

Nhóm thành module. Khi đăng ký loại bộ đệm tùy chỉnh, hãy sử dụng 'group' => 'module' để chúng xuất hiện trong phần "Tiện ích mở rộng mô-đun" của giao diện người dùng quản trị viên.

Ghi lại các sự kiện trong bộ nhớ đệm. Sử dụng cache.clearing và cache.cleared cho các bản kiểm tra, đặc biệt là trong môi trường sản xuất.

Tài nguyên liên quan

Hooks & Filters: Extending the Core — Tìm hiểu các nguyên tắc cơ bản của Hệ thống móc PolyCMS.

Tham khảo về Móc lõi & Bộ lọc — Tham chiếu đầy đủ về tất cả ~90 móc có sẵn trong lõi.

Phát triển mô-đun: Bắt đầu — Cách tạo mô-đun PolyCMS từ đầu.

Quản lý bộ đệm: Hệ thống bộ đệm dựa trên móc dành cho nhà phát triển

Tổng quan về kiến ​​trúc