Back to Main Site

PolyCMS Hooks and Filters Complete Reference for RISE CRM

Last updated on Nov 22, 2026 7:37 AM 7:37 AM 6,506.50 ms

PolyCMS for RISE CRM implements a WordPress-inspired action and filter hook engine (Blog_hooks) alongside native RISE CRM app_hooks() integration, enabling developers to extend publishing workflows, frontend markup, SEO tags, and admin screens without modifying core plugin files. This reference documents every core PolyCMS hook function, lifecycle action, content filter, SEO filter, and RISE CRM integration hook with production-ready PHP examples.

Two Types of Hooks

PolyCMS separates extensibility into two complementary mechanisms:

  • Actions: Execute custom logic at defined execution points (for example, sending a webhook after a post is published or injecting analytics markup inside <head>).
  • Filters: Intercept, transform, and return data before PolyCMS persists or renders it (for example, modifying post HTML, rewriting SEO tags, or gating content visibility).

Core PolyCMS Hook API Functions

All core PolyCMS hook helpers are defined in plugins/polycms/Helpers/polycms_hooks_helper.php and delegate to Libraries/Blog_hooks.php.

Registering an Action

polycms_add_action(string $hook, callable $callback, int $priority = 10, int $args = 1);
  • $hook - Unique name of the action hook.
  • $callback - Function name, closure, or [$object, 'method'] callable to invoke.
  • $priority - Execution order (lower numbers run earlier). Default is 10.
  • $args - Number of accepted arguments passed into the callback. Default is 1.
// Send a webhook notification whenever a post is published
polycms_add_action('polycms_post_published', function ($post) {
    $payload = [
        'event' => 'post_published',
        'id'    => (int) $post->id,
        'title' => (string) $post->title,
        'url'   => polycms_get_post_permalink($post),
    ];
    polycms_log_activity('Post published webhook queued: ' . $payload['title']);
}, 10, 1);

Registering a Filter

polycms_add_filter(string $hook, callable $callback, int $priority = 10, int $args = 1);

Filter callbacks must always return a value so downstream callbacks continue receiving valid data.

// Append a standardized editorial notice to every single post body
polycms_add_filter('polycms_post_content', function ($content) {
    return $content . '<p class="editorial-notice"><em>Views expressed belong to the respective author.</em></p>';
}, 20, 1);

Triggering and Managing Hooks

// Fire an action hook
polycms_do_action(string $hook, ...$args);

// Pass a value through all registered filter callbacks
$value = polycms_apply_filters(string $hook, $value, ...$args);

// Remove previously registered callbacks
polycms_remove_action(string $hook, callable $callback, int $priority = 10);
polycms_remove_filter(string $hook, callable $callback, int $priority = 10);

// Inspect and debug hooks during development
$has_action = polycms_has_action('polycms_head');
$has_filter = polycms_has_filter('polycms_post_content');
$fire_count = polycms_did_action('polycms_init');
$all_hooks  = polycms_get_registered_hooks('all'); // 'action', 'filter', or 'all'
$callbacks  = polycms_get_hook_callbacks('polycms_post_content', 'filter');
polycms_debug_hooks(true); // Logs hook executions at CodeIgniter debug level

Complete PolyCMS Hook Reference

Post Lifecycle Actions

Hook Fired When Parameters
polycms_post_save Immediately before a post record is written to the database $data (array)
polycms_post_saved Immediately after a post is created or updated $post (object)
polycms_post_published When a post transitions to published status $post (object)
polycms_post_delete Before a post record is deleted $post_id (int)
polycms_post_deleted After a post record is deleted $post_id (int)
polycms_post_status_changed Whenever a post status value changes $post, $old_status, $new_status

Page Lifecycle Actions

Hook Fired When Parameters
polycms_page_saved After a static page is created or updated $page (object)
polycms_page_deleted After a static page is deleted $page_id (int)

Comment Actions

Hook Fired When Parameters
polycms_comment_submitted When a visitor submits a new comment $comment (object)
polycms_comment_approved When a moderator approves a comment $comment (object)
polycms_comment_deleted When a comment is removed $comment_id (int)

Frontend Rendering and Admin UI Actions

Hook Fired When Parameters
polycms_init Right after PolyCMS finishes bootstrapping active sub-plugins None
polycms_frontend_init When the public Frontend controller initializes None
polycms_enqueue_scripts When themes or plugins enqueue frontend assets $context ('frontend')
polycms_head Inside the frontend &lt;head&gt; tag None
polycms_wp_head Fired inside polycms_head() after rendering enqueued styles None
polycms_head_meta_tags Inside &lt;head&gt; after core SEO, OG, and Twitter tags render $entity (post, page, category, tag, or null)
polycms_body_start Immediately after the opening &lt;body&gt; tag (ideal for top banners) None
polycms_footer Immediately before the closing &lt;/body&gt; tag None
polycms_wp_footer Fired inside polycms_footer() after rendering enqueued footer scripts None
polycms_footer_scripts At the end of theme footer templates after core scripts load None
polycms_single_post_view When a visitor views a single post (used by view counters and analytics) $post (object)
polycms_before_render_post Immediately before a single post view is rendered $post (object)
polycms_after_render_post Immediately after a single post view is rendered $post, $output
polycms_after_render_homepage Immediately after the blog homepage renders $output
polycms_admin_bar_actions Inside the frontend admin bar for custom staff shortcuts None
polycms_dashboard_widgets Inside the PolyCMS admin Dashboard to render custom metric widgets None
polycms_seo_box_before_fields Top of the Core SEO box in Post/Page editors (used by MTOptimize) $entity, $type
polycms_seo_box_content Inside the Core SEO box to inject extra SEO panels (used by MTOptimize) $entity, $type

Content, Layout, and Permalink Filters

Filter Applied To Input Expected Return
polycms_post_content Post body HTML before frontend display $content (string), $post Modified HTML string
polycms_post_title Post title before display $title (string) Modified title string
polycms_post_excerpt Computed post excerpt string $excerpt (string), $post Modified excerpt string
polycms_page_content Static page body HTML before display $content (string), $page Modified HTML string
polycms_the_content Unified content rendering pipeline (used by MTBuilder) $content (string), $entity Modified HTML string
polycms_post_meta Structured author, date, views, category, and tag metadata $meta (array), $post Modified metadata array
polycms_post_permalink Generated post permalink URL $permalink (string), $post Modified URL string
polycms_page_permalink Generated root-level page permalink URL $url (string), $page Modified URL string
polycms_body_class Array of CSS classes passed to &lt;body&gt; $classes (array) Modified class array
polycms_branding_display Header/footer branding mode (both, logo, brand, none) $mode (string) Modified branding mode

SEO and Customer Gate Filters

Filter Applied To Input
polycms_seo_meta_tags Data array passed into polycms_get_seo_meta_tags() $data (array)
polycms_open_graph_tags Data array passed into polycms_get_open_graph_tags() $data (array)
polycms_twitter_card_tags Data array passed into polycms_get_twitter_card_tags() $data (array)
polycms_meta_title Final document &lt;title&gt; value $title (string)
polycms_meta_description Final meta description string $description (string)
polycms_og_tags Open Graph tag array $tags (array)
polycms_twitter_tags Twitter Card tag array $tags (array)
polycms_frontend_customer_gate_enabled Whether client login is enforced on frontend routes $enabled (bool)
polycms_frontend_customer_gate_authorized Whether current visitor passes the client login gate $authorized (bool)
polycms_frontend_customer_gate_login_url Redirect login URL for unauthorized frontend visitors $login_url (string)
polycms_frontend_customer_gate_bypass Allow specific URIs to bypass the client login gate $bypass (bool), $request_uri

Plugin and Theme Lifecycle Actions

Hook Fired When Parameters
polycms_plugin_installed After a sub-plugin ZIP is uploaded and registered $plugin_file (string)
polycms_plugin_activated When a sub-plugin is activated in PolyCMS > Plugins $plugin_file (string)
polycms_plugin_deactivated When a sub-plugin is deactivated in PolyCMS > Plugins $plugin_file (string)
polycms_plugin_settings_save_{slug} When a sub-plugin settings form submits (- replaced with _) $post_data (array)
polycms_theme_loaded Right after the active theme and its functions.php initialize $theme (object)
polycms_theme_switched When an administrator switches the active frontend theme $new_theme, $old_theme

RISE CRM Integration Hooks Used by PolyCMS

In addition to its internal Blog_hooks engine, PolyCMS registers directly with RISE CRM's native CodeIgniter 4 hook dispatcher via app_hooks(). Understanding these integration points is essential when building advanced plugins that interact with RISE navigation, permissions, or security middleware.

RISE CRM Hook Type How PolyCMS Uses It
app_filter_staff_left_menu Filter Injects the PolyCMS and Appearance sidebar groups, triggers admin_init, and merges active sub-plugin menu.json entries
app_filter_client_left_menu Filter Adds the optional Blog link to the RISE Client Portal sidebar when polycms_show_in_client_menu is enabled
app_hook_role_permissions_extension Action Renders the 5 granular PolyCMS RBAC checkboxes (polycms_view, polycms_create, polycms_edit, polycms_delete, polycms_settings) inside Settings > Access Permission > Roles
app_filter_role_permissions_save_data Filter Persists checked PolyCMS permissions when saving a RISE staff role
app_filter_app_csrf_exclude_uris Filter Automatically excludes cms/api/v1.*+ from RISE CSRF validation so stateless REST API clients can call POST, PUT, and DELETE endpoints
app_hook_head_extension Action Enqueues PolyCMS Bootstrap 5 compatibility styles (rise-bs5-compat.css), Select2, and TinyMCE editor CSS strictly on PolyCMS admin routes
app_hook_layout_main_view_extension Action Loads TinyMCE, SweetAlert2, and Select2 scripts on PolyCMS admin routes and fires the bridged app_admin_footer action for sub-plugins such as MTBuilder
app_hook_before_app_access Action Evaluates the optional homepage redirect setting (polycms_enable_homepage_redirect, disabled by default on RISE CRM to protect /dashboard and /signin)
// Example: Register a custom RISE CRM staff menu item using app_hooks()
app_hooks()->add_filter('app_filter_staff_left_menu', function ($sidebar_menu) {
    if (!polycms_is_admin() && !polycms_staff_can('view', 'polycms')) {
        return $sidebar_menu;
    }

    if (isset($sidebar_menu['polycms']['submenu'])) {
        $sidebar_menu['polycms']['submenu'][] = [
            'name'                => 'Editorial Calendar',
            'url'                 => polycms_admin_url('polycms/plugins/settings/editorial-calendar'),
            'is_custom_menu_item' => true,
        ];
    }

    return $sidebar_menu;
}, 20);

Practical PHP Examples

Example 1: Auto-Generate Clean Excerpts

polycms_add_filter('polycms_post_excerpt', function ($excerpt, $post = null) {
    if (empty($excerpt) && is_object($post) && !empty($post->content)) {
        $plain = trim(strip_tags($post->content));
        return mb_substr($plain, 0, 160, 'UTF-8') . '...';
    }
    return $excerpt;
}, 10, 2);

Example 2: Inject Google Tag Manager into Frontend Head

polycms_add_action('polycms_head', function () {
    $gtm_id = trim((string) polycms_get_option('polycms_gtm_id', ''));
    if ($gtm_id !== '' && !polycms_is_staff_logged_in()) {
        $safe_id = html_escape($gtm_id);
        echo "<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});"
            . "var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;"
            . "j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})"
            . "(window,document,'script','dataLayer','{$safe_id}');</script>\n";
    }
});

Example 3: Restrict Private Posts to Logged-In RISE Staff

polycms_add_filter('polycms_post_content', function ($content, $post = null) {
    $CI = &polycms_ci();
    if (!$post) {
        $post = $CI->load->get_var('post');
    }

    if (is_object($post) && ($post->visibility ?? 'public') === 'private' && !polycms_is_staff_logged_in()) {
        return '<div class="alert alert-warning">This content is restricted to authorized team members.</div>';
    }

    return $content;
}, 10, 2);

Best Practices

  1. Declare explicit priorities: Default priority is 10. Use lower numbers (such as 5) to run before core or bundled plugins, and higher numbers (such as 20) to run afterward.
  2. Always return a value in filters: Omitting return breaks the filter chain and can produce empty HTML output.
  3. Use collision-proof PolyCMS helpers: Always prefer polycms_ci(), polycms_get_option(), and polycms_is_staff_logged_in() over legacy globals so your code coexists cleanly with other RISE CRM plugins.
  4. Prefix callback names or use closures: Prefix global functions with your plugin slug (for example, myplugin_) to avoid PHP function name collisions.
  5. Keep filters pure: Avoid mutating database rows or global state inside rendering filters; use dedicated lifecycle actions instead.

Related Documentation