Troubleshooting
Common issues when using wpzylos-hooks.
Hook Not Firing
Callback never executes
Problem: wpAction('init', $callback) — callback never runs.
Cause: Hook registered after WordPress already fired that hook.
Fix: Register hooks early, typically in plugins_loaded:
add_action('plugins_loaded', function () use ($app) {
$app->boot(); // Registers hooks in providers
}, 10);
Wrong priority
Problem: Callback runs but data is unexpected.
Cause: Another plugin modified data before/after your callback.
Fix: Adjust priority:
// Run earlier (before default 10)
$hooks->wpFilter('the_content', $callback, 5);
// Run later (after most plugins)
$hooks->wpFilter('the_content', $callback, 99);
Prefixing Issues
Custom hook not received by listeners
Problem: do_action($context->hook('my_event')) — no listeners fire.
Cause: Listener uses unprefixed hook name.
Fix: Listeners must use same prefixed name:
// Firing
$hooks->doAction('my_event', $data);
// Actually fires: myplugin_my_event
// Listening (must match)
add_action('myplugin_my_event', function ($data) {});
// OR use context
add_action($context->hook('my_event'), function ($data) {});
WordPress hook accidentally prefixed
Problem: init hook not firing — became myplugin_init.
Cause: Used custom hook method instead of WordPress hook method.
Fix: Use correct method:
// Bad: Wrong: doAction prefixes
$hooks->doAction('init', $data);
// Good: Correct: wpAction never prefixes
$hooks->wpAction('init', $callback);
Removal Issues
Can't remove anonymous function
Problem: remove_action fails for closure.
Cause: PHP closures have unique identities.
Fix: Store reference or use named function:
// Bad: Can't remove - different closure instance
$hooks->wpAction('init', fn() => doSomething());
remove_action('init', fn() => doSomething()); // Fails
// Good: Store reference
$callback = fn() => doSomething();
$hooks->wpAction('init', $callback);
$hooks->remove('init', $callback);
Remove not working
Problem: remove_action returns false.
Cause: Wrong priority or callback signature.
Fix: Match priority used during registration:
// Registration
$hooks->wpAction('init', $callback, 15);
// Removal (must match priority)
remove_action('init', $callback, 15);
Filter Issues
Filter returns wrong type
Problem: Filter returns null unexpectedly.
Cause: Callback doesn't return value.
Fix: Always return in filters:
// Bad: Missing return
$hooks->wpFilter('the_title', function ($title) {
$modified = $title . ' - Site';
// Forgot return!
});
// Good: Return value
$hooks->wpFilter('the_title', function ($title) {
return $title . ' - Site';
});