Tham khảo về Móc & Bộ lọc: Hướng dẫn hoàn chỉnh dành cho nhà phát triển

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

Đối tượng: Nhà phát triển — Yêu cầu kiến ​​thức về PHP / Laravel. Danh mục: Tham khảo kỹ thuật — Tài liệu kỹ thuật dành cho nhà phát triển tích hợp.

Bạn sẽ học được gì

• Hiểu cơ chế Action vs Filter trong PolyCMS

• Tra cứu tên hook, thông số, vị trí điều phối

• Đăng ký hook từ theme functions.php và module ServiceProvider

• Sử dụng mức độ ưu tiên để kiểm soát thứ tự thực hiện

• Áp dụng các use-case thực tế cho từng nhóm hook

1. Giới thiệu về Hook System

PolyCMS sử dụng hệ thống Hook/Filter giống như WordPress, được xây dựng nguyên bản trên Laravel:

• Action (Hook::doAction): Thực thi các tác dụng phụ (ghi nhật ký, gửi email, đồng bộ hóa dữ liệu). Không cần giá trị trả về.

• Filter (Hook::applyFilters): Nhận một giá trị, sửa đổi nó và phải trả về giá trị đã sửa đổi.

Cú pháp cơ bản

use App\Facades\Hook;

// Register an Action
Hook::addAction('order_completed', function ($order) {
    Mail::to($order->user)->send(new OrderCompletedMail($order));
}, priority: 10);

// Register a Filter
Hook::addFilter('post.default_image', function (?string $imageUrl, $post) {
    if ($post?->categories->contains('slug', 'news')) {
        return '/images/news-default.jpg';
    }
    return $imageUrl;
}, priority: 10);

2. Nội dung & Bài viết

Bộ lọc

Hành động

Các trường hợp sử dụng thực tế

UC1 — Hình thu nhỏ mặc định dành riêng cho danh mục: Giữ hình thu nhỏ mặc định cụ thể cho từng danh mục khi bài đăng không có hình ảnh nổi bật:

Hook::addFilter('post.default_image', function (?string $url, $post) {
    if ($post?->categories->contains('slug', 'tech')) return '/images/defaults/tech.jpg';
    if ($post?->categories->contains('slug', 'lifestyle')) return '/images/defaults/lifestyle.jpg';
    return $url; // fallback to admin setting
});

UC2 — Cấu trúc URL Wiki: Giảm hạng/thay đổi cấu trúc URL bài đăng từ /posts/slug thành /docs/slug để có bố cục kiểu wiki:

Hook::addFilter('post.frontend_url', function ($url, $post) {
    return ($post->type === 'wiki') ? '/docs/' . $post->slug : $url;
});

UC3 — Tự động chèn quảng cáo nội tuyến: Tự động chèn các khối biểu ngữ quảng cáo sau đoạn thứ 3 của bài đăng:

Hook::addFilter('content.render.html', function (string $html) {
    $adBanner = '<div class="ad-inline">Advertisement</div>';
    $parts = explode('</p>', $html, 4);
    if (count($parts) > 3) {
        $parts[2] .= '</p>' . $adBanner;
        return implode('</p>', $parts);
    }
    return $html;
});

3. Thư viện phương tiện

Bộ lọc

Hành động

Các trường hợp sử dụng thực tế

UC1 — Viết lại URL CDN: Tích hợp với Cloudflare R2 hoặc Amazon S3, tự động chuyển đổi đường dẫn lưu trữ cục bộ sang URL CDN:

Hook::addFilter('media.url', function (string $url, $media) {
    return str_replace('/storage/', 'https://cdn.mysite.com/', $url);
});

UC2 — Bảo vệ tài sản hệ thống quan trọng: Ngăn chặn việc vô tình xóa bất kỳ hình ảnh nào hiện đang được sử dụng làm biểu trưng của trang web:

Hook::addFilter('media.delete.should', function (bool $allow, $media) {
    $logoUrl = get_option('site_logo', null, 'general');
    return ($media->url === $logoUrl) ? false : $allow;
});

UC3 — Tự động tối ưu hóa hình ảnh khi tải lên: Gửi hàng đợi nền để tạo hình ảnh WebP nhẹ từ các video tải lên tiêu chuẩn:

Hook::addAction('media.uploaded', function ($media, $file) {
    if (str_starts_with($media->mime_type, 'image/')) {
        dispatch(new ConvertToWebpJob($media));
    }
});

4. Thương mại điện tử - Đơn đặt hàng & Hoàn tiền

Hành động

Bộ lọc

Các trường hợp sử dụng thực tế

UC1 — Thông báo Telegram cho đơn đặt hàng mới:

Hook::addAction('order_status_updated', function ($order, $old, $new) {
    if ($old === 'pending' && $new === 'processing') {
        TelegramBot::send(" Order #{$order->code} has been confirmed!");
    }
});

UC2 — Điểm thưởng trung thành khi hoàn thành đơn hàng:

Hook::addAction('order_completed', function ($order) {
    if ($order->user_id) {
        $points = (int) floor($order->total / 10); // 1 point per $10 spent
        LoyaltyService::addPoints($order->user_id, $points, "Order #{$order->code}");
    }
});

UC3 — Ghi nhật ký kiểm tra các khoản tiền hoàn lại không thành công:

Hook::addAction('order.refund.failed', function ($order, $data, $exception, $userId) {
    AuditLog::create([
        'action' => 'refund_failed',
        'order_id' => $order->id,
        'user_id' => $userId,
        'reason' => $exception->getMessage(),
    ]);
});

5. Thương mại điện tử - Giỏ hàng, Vận chuyển, Thuế, Hàng tồn kho

Bộ lọc

Hành động

Các trường hợp sử dụng thực tế

UC1 — Giao hàng miễn phí cho đơn hàng trên $100:

Hook::addFilter('shipping.calculate_cost', function ($cost, $method, $cart) {
    $subtotal = collect($cart->items)->sum(fn($i) => $i->price * $i->quantity);
    return ($subtotal >= 100) ? 0 : $cost;
});

UC2 — Chặn đánh giá nếu người dùng chưa mua sản phẩm:

Hook::addFilter('review.can_submit', function (bool $allowed, $user, $product) {
    $hasPurchased = Order::where('user_id', $user->id)
        ->where('status', 'completed')
        ->whereHas('items', fn($q) => $q->where('product_id', $product->id))
        ->exists();
    return $hasPurchased;
});

UC3 — Theo dõi pixel của Facebook cho sự kiện AddToCart:

Hook::addAction('cart.item.added', function ($item, $cart) {
    session()->push('fb_pixel_events', [
        'event' => 'AddToCart',
        'product_id' => $item->product_id,
        'value' => $item->price,
    ]);
});

6. Thương mại điện tử - Cổng thanh toán

Bộ lọc

Ca sử dụng thực tế: Thêm trường tùy chỉnh vào cổng Chuyển khoản ngân hàng:

Hook::addFilter('payment.gateway.config_schema', function ($schema, $gateway) {
    if ($gateway->code === 'bank_transfer') {
        $schema['branch_code'] = [
            'type' => 'text', 'label' => 'Branch Code', 'required' => false,
        ];
    }
    return $schema;
});

7. Chủ đề & Hình thức

Bộ lọc

Hành động

Các trường hợp sử dụng thực tế

UC1 — Chèn biểu ngữ quảng cáo từ mô-đun:

Hook::addFilter('frontend.topbar.banners', function (array $banners) {
    $banners[] = [
        'text' => ' Flash Sale — 30% Off Today!',
        'url' => '/sale',
        'bg_color' => '#ff4444',
    ];
    return $banners;
});

UC2 — Phần chèn đầu của Google Analytics:

Hook::addAction('cms_head', function () {
    $ga = get_option('google_analytics_id', null, 'seo');
    if ($ga) {
        echo "<script async src='https://www.googletagmanager.com/gtag/js?id={$ga}'></script>";
    }
});

UC3 — Tải biến thanh bên các bài đăng phổ biến:

Hook::addFilter('theme.view.data', function ($data, $viewName) {
    if ($viewName === 'posts.index') {
        $data['popular_posts'] = Post::orderBy('views', 'desc')->limit(5)->get();
    }
    return $data;
});

8. Cài đặt & Cấu hình

Bộ lọc

Hành động

Các trường hợp sử dụng thực tế

UC1 — Đăng ký phần cài đặt tùy chỉnh qua Mô-đun:

Hook::addFilter('settings.defaults', function ($defaults) {
    $defaults['mymodule'] = [
        'mymodule_api_key' => [
            'key' => 'mymodule_api_key', 'value' => '', 'type' => 'text',
            'label' => 'API Key', 'description' => 'Enter your API key',
        ],
    ];
    return $defaults;
});

UC2 — Xóa bộ đệm định tuyến trên bản cập nhật Permalinks:

Hook::addAction('settings.saved', function ($payload) {
    if (($payload['group'] ?? '') === 'permalinks') {
        Artisan::call('route:clear');
        Cache::tags('routes')->flush();
    }
});

9. Người dùng, Vai trò & Xác thực

Bộ lọc

Hành động

Các trường hợp sử dụng thực tế

UC1 — Bộ chặn xác thực đa yếu tố:

Hook::addFilter('auth.login.pre_token', function ($response, $user, $request) {
    if ($user->hasRole('admin') && !$request->filled('otp_code')) {
        return response()->json(['requires_2fa' => true, 'user_id' => $user->id], 403);
    }
    return $response; // null = continue token generation
});

UC2 — Email chào mừng khi đăng ký người dùng:

Hook::addAction('user.creating', function ($data) {
    dispatch(new SendWelcomeEmail($data['email'], $data['name']));
});

##10. SEO

Bộ lọc

Trường hợp sử dụng thực tế - URL chuẩn cho thiết lập đa ngôn ngữ:

Hook::addFilter('seo.canonical_url', function (string $url) {
    $locale = app()->getLocale();
    if ($locale !== 'en') {
        return url("/{$locale}" . parse_url($url, PHP_URL_PATH));
    }
    return $url;
});

11. Tiện ích

Bộ lọc

Hành động

Ca sử dụng thực tế — Đăng ký loại tiện ích "Bản đồ cửa hàng":

Hook::addAction('widgets.register_types', function ($manager) {
    $manager->registerType('store_map', [
        'label' => 'Store Map',
        'description' => 'Google Maps showing store locations',
        'fields' => [
            'api_key' => ['type' => 'text', 'label' => 'Google Maps API Key'],
            'lat' => ['type' => 'text', 'label' => 'Latitude'],
            'lng' => ['type' => 'text', 'label' => 'Longitude'],
        ],
        'view' => 'widgets.store-map',
    ]);
});

12. Điều hướng & Biên tập của Quản trị viên

Bộ lọc

Hành động

Trường hợp sử dụng thực tế - Thêm mục menu trạng thái SEO tùy chỉnh vào thanh trên cùng:

Hook::addFilter('topbar.menu.items', function (array $items, $request, $user) {
    $items[] = [
        'key' => 'seo_score',
        'label' => 'SEO Score',
        'icon' => 'chart-bar',
        'url' => '/admin/seo/score',
        'position' => 50,
    ];
    return $items;
});

13. Mô-đun

Bộ lọc

Hành động

Ca sử dụng thực tế — Tự động chạy di chuyển khi kích hoạt mô-đun:

Hook::addAction('module.activating', function ($moduleKey, $module) {
    Artisan::call('migrate', [
        '--path' => "modules/Polyx/{$moduleKey}/database/migrations",
        '--force' => true,
    ]);
});

14. Khởi động hệ thống

Hành động

Trường hợp sử dụng thực tế - Mô-đun đăng ký các khả năng/quyền tùy chỉnh:

Hook::addAction('roles.register_permissions', function ($registry) {
    $registry->register('manage analytics', 'Analytics', 'View and manage analytics dashboard');
    $registry->register('export reports', 'Analytics', 'Export analytics reports to CSV');
});

##Bài viết liên quan

• Tổng quan về Hooks & Filters — Tổng quan chung về hệ thống sự kiện

• Phát triển chủ đề — Bắt đầu với các chủ đề tùy chỉnh

• Phát triển mô-đun — Bắt đầu với các mô-đun tùy chỉnh

• Xác thực API REST — Xác thực ứng dụng khách API