Hook

Syntax

Hook:<filter_or_action_slug>
Hook:<filter_or_action_slug>:<priority>
Hook:<filter_or_action_slug>:* - Premium Feature

Note! If priority is not specified, it defaults to 10. With premium add-on, you can define a wildcard priority * (e.g. Hook:all_plugins:*).

Definition

Focus on a specific hook (action or filter) and choose to either prevent its execution or intervene in the filter chain to alter the outcome according to the specified “Effect” property. This directive applies solely to actions and filters established subsequent to the WordPress core action init.

A comprehensive grasp of WordPress filters and actions is essential for harnessing the potential of managing hooks, particularly concerning the sequencing of execution priorities.

Currently, AAM facilitates the following effects:

deny: Eliminates execution of all callback functions for a designated filter or action.
alter: Modify the response value. This category incorporates additional functionalities to regulate the overriding process, detailed further below. It’s noteworthy that this effect permits the original callback function’s execution, only modifying the return value.
merge: Assumes the returned value to be an array and merge it with the specified array values.
replace: Removes registered callback functions for the specified hook and returns the provided value instead.

Deny Effect

The “deny” effect completely eradicates registered callback functions associated with any given action or filter. Since WordPress permits the registration of multiple callback functions for the same hook with varying priorities, it’s necessary to explicitly specify which priority to deny.

For instance, the following policy effectively halts the execution of all registered functions for the admin_menu WordPress core action at the default priority of 10. Consequently, no plugins or themes can register a new admin menu.

{
    "Statement": {
        "Effect": "deny",
        "Resource": "Hook:admin_menu"
    }
}

It’s crucial to note that the above example targets the default priority 10. While most plugin/theme developers typically don’t alter this priority, exceptions may exist. Hence, the premium add-on allows for the targeting of all priorities using the wildcard * annotation. This ensures denial of all callback functions across all priorities. The following statement targets all callbacks:

{
    "Statement": [
        {
            "Effect": "deny",
            "Resource": "Hook:admin_menu:*"
        }
    ]
}

Note! In the example above, the wildcard * (asterisk) functionality is exclusive to the premium add-on. It enables the targeting of all priorities, offering assistance when unsure about the registered callback priority.

Alter Effect

The “alter” effect allows you to modify the final result of a given filter. It’s important to note that this effect doesn’t prevent the execution of registered callback functions; it solely modifies the ultimate return value. To stop the execution of registered functions altogether, you should utilize the replace effect instead.

Note! The “alter” effect is intended for targeting WordPress filters exclusively; it has no impact on actions since actions, by nature, do not return results.

In the following example, we demonstrate the use of the “alter” effect to alter the behavior of the WordPress core filter screen_options_show_screen, thereby inhibiting user interaction with the “Screen Options” button located in the top right corner of nearly all default WordPress backend pages.

{
    "Statement": [
        {
            "Effect": "alter",
            "Resource": "Hook:screen_options_show_screen",
            "Return": false
        }
    ]
}

To enhance the manipulation of return values, you can employ the &:filter(...) annotation within the Return property. Here’s how it operates.

The &:filter(...) annotation is a specialized syntax designed exclusively for the Hook resource. It’s intended to be utilized within the Return property. Within the parentheses, you specify the comparison expression, where:

The left operand can either be the reserved keyword $key or $value. $key represents a key within an associative array or a property name within an object, while $value represents an actual value. $value can also denote a full path to any value within complex data structures, such as $value.roles[0].name.
The comparison operator can be any of the following: == (equals), *= (contains), ^= (starts with), $= (ends with), != (not equals), > (greater than), < (less than), >= (greater or equals to), <= (less than or equals to).
More complex comparison operator can be used. The in or ∈ checks if $key or $value is in array of values. The !in or ∉ checks if it is not. For example: &:filter($key !in [de,fr]).
The right operand is the static value used to compare with the left operand based on the comparison operator.

The following examples illustrate how this works in practice:

Retain only the value in the array/object associated with the a key/property:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($key == a)"
    }
}

@tab php

<?php

print_r(apply_filters('aam_test_filter', [
    'c' => 0,
    'a' => 1
]));

// The returned value will be:
// Array (
//  'a' => 1
// )

:::

Remove the a key/property from the array/object:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($key != a)"
    }
}

@tab php

<?php

print_r(apply_filters('aam_test_filter', [
    'c' => 0,
    'a' => 1
]));

// The returned value will be:
// Array (
//  'c' => 0
// )

:::

Retain only values in the array/object that contain the dev string in a key/property:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($key *= dev)"
    }
}

@tab php

<?php

print_r(apply_filters(
    'aam_test_filter',
    [
        'jodev' => 'a',
        'more' => 'b',
        'deno' => 'c'
    ]
));

// The returned value will be:
// Array (
//  'jodev' => 'a'
// )

:::

Retain only values in the array/object that start with the dev string in a key/property:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($key ^= dev)"
    }
}

@tab php

<?php

print_r(apply_filters(
    'aam_test_filter',
    [
        'jodev' => 'a',
        'devo' => 'b',
        'deno' => 'c'
    ]
));

// The returned value will be:
// Array (
//  'devo' => 'b'
// )

:::

Retain only values in the array/object that end with the no string:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($value $= on)"
    }
}

@tab php

<?php

print_r(apply_filters(
    'aam_test_filter',
    [
        'a' => 'carbon',
        'b' => 'banana',
        'c' => 'orange'
    ]
));

// The returned value will be:
// Array (
//  'a' => 'carbon'
// )

:::

Remove values that are not equal to hello:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($value != hello)"
    }
}

@tab php

<?php

print_r(apply_filters(
    'aam_test_filter',
    [
        'a' => 'one',
        'b' => 'hello',
        'c' => 'two'
    ]
));

// The returned value will be:
// Array (
//  'b' => 'hello'
// )

:::

Filter complex return values:

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": "&:filter($value.test[0].test != hello)"
    }
}

@tab php

<?php

print_r(apply_filters(
    'aam_test_filter',
    [
        [
            'test' => [
                [
                    'test' => 'no'
                ]
            ]
        ],
        [
            'test' => [
                [
                    'test' => 'hello'
                ]
            ]
        ]
    ]
));

// The returned value will be:
// Array (
//  'test' => Array (
//      Array (
//          'test' => 'no'
//      )
//   )
// )

:::

Additionally, you can provide the array of filters. In this case, the return value will be transformed sequentially through the list of provided filters.

::: code-tabs

@tab json

{
    "Statement": {
        "Effect": "alter",
        "Resource": "Hook:aam_test_filter:10",
        "Return": [
            "&:filter($key != hello)",
            "&:filter($value > 5)"
        ]
    }
}

@tab php

<?php

print_r(apply_filters(
    'aam_test_filter',
    [
        'hello' => 1,
        'a'     => 4,
        'b'     => 5,
        'c'     => 10
    ]
));

// The returned value will be:
// Array (
//  'c' => 10
// )

:::

Merge Effect

The “merge” effect operates similarly to “alter”, modifying the final return value. However, it anticipates the return value to be a valid array. If it is indeed an array, the “merge” effect combines it with additional values specified in the MergeWith property.

In the following example, we include an additional list of trusted domains:

{
    "Statement": [
        {
            "Effect": "merge",
            "Resource": "Hook:allowed_redirect_hosts",
            "MergeWith": [
                "members.aamportal.com",
                "store.aamportal.com"
            ]
        }
    ]
}

Replace Effect

In contrast to the “merge” or “alter” effects, the “replace” dynamically removes all callback functions for a given priority or for all priorities simultaneously (if the wildcard * annotation is utilized). Instead, it provides the value specified in the Return property. This effect proves valuable when aiming to prevent the execution of any registered callback functions.

The following statement ensures that no other plugins or themes execute their functionality concerning the ability to change a user’s password on the profile page:

{
    "Statement": [
        {
            "Effect": "replace",
            "Resource": "Hook:show_password_fields:*",
            "Return": false
        }
    ]
}