Hooks Overview

warning

Never paste unreviewed PHP into production. One syntax error in functions.php can take the site down.

Hooks Overview Explained

Hook type	What it does	When you use it	Example
Action	Runs code at a point in execution	Add markup, enqueue assets, run side-effects	add_action( 'generate_before_header', 'my_banner' )
Filter	Transforms a value and returns it	Change layout decisions, text, settings	add_filter( 'generate_sidebar_layout', 'my_layout' )

GeneratePress adds many theme-specific hook points prefixed with generate_.

Why It Matters

• Hooks are the main "API" for customizing GeneratePress without forking templates.
• Hook-first customizations survive theme updates and are easier to revert.
• Hooks make debugging faster: you can search for the hook name and see exactly where it runs.

How It Works

GeneratePress defines hook points with do_action() and filter points with apply_filters(). Default theme behavior is attached with add_action() / add_filter(). Your child theme adds additional callbacks.

flowchart LR
  POINT[do_action / apply_filters] --> DEFAULT[GeneratePress callback]
  POINT --> YOURS[Child theme callback]
  YOURS --> OUT[HTML/CSS/JS changes]

Practical Walkthrough

Step 1: List Hook Points in the Theme

list-generatepress-hook-points.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "do_action( 'generate_" -n inc templates | head -n 50

Step 2: See Which Callbacks Are Attached by Default

list-default-generatepress-callbacks.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "add_action( 'generate_" -n inc | head -n 50

Step 3: List Theme Filters You Can Override

list-generatepress-filters.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "apply_filters( 'generate_" -n inc templates | head -n 50

Step 4: Add a Safe Test Hook in a Child Theme

wp-content/themes/generatepress-child/functions.php

<?php

add_action( 'generate_before_header', function() {
    echo '<div class="gp-notice">Hello from the child theme</div>';
} );

CLI sanity check (validate file exists):

verify-child-theme-files.sh

cd /var/www/html
test -f wp-content/themes/generatepress-child/functions.php && echo "child functions.php OK"

Practical Examples

Example 1: Add a Footer Copyright Line

wp-content/themes/generatepress-child/functions.php

<?php

add_action( 'generate_footer', function() {
    echo '<small class="gp-footer-meta">© ' . esc_html( gmdate( 'Y' ) ) . ' Example Co.</small>';
} );

Example 2: Filter the Sidebar Layout on Posts

wp-content/themes/generatepress-child/functions.php

<?php

add_filter( 'generate_sidebar_layout', function( $layout ) {
    if ( is_single() ) {
        return 'right-sidebar';
    }

    return $layout;
} );

Example 3: Remove a Default Callback (Pattern)

Sometimes you want to disable a default behavior. The workflow is:

1. Find the add_action() line in the parent theme.
2. Copy the hook name, callback name, and priority.
3. Use remove_action() in the child theme.

wp-content/themes/generatepress-child/functions.php

<?php

add_action( 'after_setup_theme', function() {
    // Example pattern only: replace hook/callback/priority with real values you found via grep.
    // remove_action( 'generate_after_header', 'generate_some_callback', 10 );
} );

Best Practices

Practice	Why
Prefix custom functions/classes	Avoid collisions with plugins/themes
Escape output	Prevent XSS and broken markup
Keep callbacks small	Easier rollback and fewer side effects
Use priorities intentionally	Control ordering when multiple callbacks target the same hook
Prefer filters for decisions, actions for output	Keeps logic predictable

Troubleshooting

Symptom	Cause	Fix
Site white screen	PHP syntax error	Check /usr/local/lsws/logs/error.log, fix functions.php, and redeploy
Hook output appears twice	Callback registered twice	Search for duplicate add_action and remove one
Hook not firing	Wrong hook name or wrong location	Confirm hook exists with grep -R "do_action( 'hook'" -n
Output breaks layout	Missing wrapper styles	Add minimal CSS and avoid extra containers

Hands-On

1. Pick one hook point near the header and one near the footer.
2. Add a static message to each using actions.
3. Remove both messages and confirm your deploy workflow can roll back cleanly.

Quick Reference

hook-discovery-cheatsheet.sh

cd /var/www/html/wp-content/themes/generatepress

# Hook points
grep -R "do_action( 'generate_" -n inc templates | head

# Default callbacks
grep -R "add_action( 'generate_" -n inc | head

What's Next

• Next: Child Theme Setup (overview)
• Related: Global Layout Framework