Hooks

The Hooks Service (AAM_Framework_Service_Hooks) is a runtime access-control layer for WordPress hooks (actions and filters). It allows you to deny, allow, modify, merge, or fully replace hook execution behavior without changing the underlying plugin or theme code.

It operates as a policy engine on top of WordPress hooks system, dynamically applying rules per access level (user/visitor/admin context) and priority.

At a high level, this service:

• Intercepts WordPress filters via add_filter / remove_all_filters
• Stores hook policies in an access-level resource
• Applies runtime transformations to hook output
• Optionally listens and enforces hooks per user/visitor context

# Definition

class AAM_Framework_Service_Hooks {

    public deny(string $hook, string|int $priority = 10) : bool
    public allow(string $hook, string|int $priority = 10) : bool
    public alter(string $hook, mixed $return, string|int $priority = 10) : bool
    public merge(string $hook, array $data, string|int $priority = 10) : bool
    public replace(string $hook, mixed $value, string|int $priority = 10) : bool

    public reset() : bool
}

# Core Concept

Each hook rule is stored as a permission record:

[
  'name'     => 'hook_name',
  'priority' => 10,
  'effect'   => 'deny|allow|alter|merge|replace',
  'return'   => mixed (optional)
]

The service converts these rules into runtime WordPress filter behavior.

# Methods

# deny()

Prevents execution of all callbacks registered at a specific hook priority.

public function deny(string $hook, string|int $priority = 10) : bool

# Behavior

• Stores a "deny" policy

• Internally calls:

  remove_all_filters($hook, $priority)
  

# Use Case

• Disable plugin behavior at runtime
• Block unwanted integrations

# Example

$hooks->deny('wp_mail', 10);

# allow()

Explicitly marks a hook as allowed (used for governance consistency).

public function allow(string $hook, string|int $priority = 10) : bool

# Behavior

• Registers policy as allow
• Does not alter execution directly
• Used for access-level auditing and normalization

# Example

$hooks->allow('the_content', 10);

# alter()

Overrides the return value of a hook with a custom value or transformation.

public function alter(string $hook, mixed $return, string|int $priority = 10) : bool

# Behavior

• Registers a filter callback
• Replaces output using _override_return_value()

# Supported override types:

• scalar value (direct replacement)
• string filter expression
• array of filter expressions

# Example

$hooks->alter('the_title', 'New Title');

# merge()

Merges the original hook output with additional data.

public function merge(string $hook, array $data, string|int $priority = 10) : bool

# Behavior

• Applies array_merge() to hook output
• Only meaningful when output is array-like

# Example

$hooks->merge('wp_nav_menu_items', [
    'extra_item' => 'Dashboard'
]);

# Internal logic

array_merge(original_value, injected_data)

# replace()

Completely replaces hook execution output and removes all existing filters at that priority.

public function replace(string $hook, mixed $value, string|int $priority = 10) : bool

# Behavior

• Executes:

  remove_all_filters($hook, $priority)
  

• Registers a new callback returning fixed value

# Example

$hooks->replace('the_content', 'Access Restricted');

# reset()

Removes all hook permissions for the current access level.

public function reset() : bool

# Behavior

• Clears all stored hook policies from resource layer

# Example

$hooks->reset();

# listen()

Attaches runtime listeners to hooks based on defined policies.

public function listen($hook = null)

# Behavior

• Works only for:

  • USER
  • VISITOR access levels

• Registers runtime enforcement callbacks

• Does NOT persist new DB permissions when $hook is provided

# Listen to all hooks

$hooks->listen();

Registers all stored hook policies.

# Listen to specific hook

$hooks->listen([
  'name' => 'the_content',
  'priority' => 10
]);

# Hook Effects

# deny

Hard stop execution at priority level.

# alter

Overrides return value using:

_override_return_value()

Supports:

• scalar replacement
• filter expressions
• chained transformations

# merge

Combines arrays:

array_merge(original, injected)

# replace

Fully replaces execution chain.

# Expression System (Advanced)

The service supports filter expressions inside strings and arrays.

# Syntax

&:filter(condition)

# Example

&:filter($value == "admin")

# Supported Operators

# Array filtering

If all items are filter expressions:

[
  &:filter($value == "admin"),
  &:filter($value != "guest")
]

They are executed as a filter chain.

# Listener Behavior

When _modify() is triggered:

• Registers a single closure per hook
• Ensures idempotent registration
• Applies transformation at runtime

# Execution flow:

$value → alter/merge logic → return modified value

# Error Handling

Every public method is wrapped:

try {
    ...
} catch (Exception $e) {
    $result = $this->_handle_error($e);
}

So the service is:

• fault-tolerant
• safe for runtime enforcement
• non-breaking for WordPress execution

# Access Level Restrictions

listen() only works for:

• USER
• VISITOR

Any other access level throws:

LogicException: Only user and visitor access level can listen to a hook