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 <head> tag |
None |
polycms_wp_head |
Fired inside polycms_head() after rendering enqueued styles |
None |
polycms_head_meta_tags |
Inside <head> after core SEO, OG, and Twitter tags render |
$entity (post, page, category, tag, or null) |
polycms_body_start |
Immediately after the opening <body> tag (ideal for top banners) |
None |
polycms_footer |
Immediately before the closing </body> 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 <body> |
$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 <title> 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
- 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.
- Always return a value in filters: Omitting
return breaks the filter chain and can produce empty HTML output.
- 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.
- Prefix callback names or use closures: Prefix global functions with your plugin slug (for example,
myplugin_) to avoid PHP function name collisions.
- Keep filters pure: Avoid mutating database rows or global state inside rendering filters; use dedicated lifecycle actions instead.
Related Documentation