Param

# Syntax

{
    "Key": "string",
    "Value": "mixed",
    "Enforce": "boolean",
    "Condition": "object"
}

# Definition

Policy may carry some parameters that support statements or are used to override any WordPress core options.

Each param has the Key and Value properties. The param's key can be used with POLICY_PARAM marker or in the code to programmatically fetch its value.

{
    "Param": [
        {
            "Key": "post:default:category",
            "Value": 345
        }
    ]
}

// This code will return int value 345 if current user has
// Param `post:default:category` defined in attached policy
AAM::api()->getAccessPolicyManager()->getParam('post:default:category');

# Key

• Type: String (case-sensitive)
• Required

The Key attribute has to contain a string value. There is no limit to how long the string can be and it is up to your discretion to name the param in a meaningful way. The only recommendation here is to stay consistent with naming and formatting patterns.

The Key attribute can be dynamically declared using markers, which can be leveraged to create one or multiple params during runtime. If dynamic marker returns an array of strings, this signals AAM to declare multiple params as described below with "mapping operand".

For instance, suppose you wish to create a param with the name that reflects your current website environment:

{
    "Key": "${ENV.name}",
    "Value": "This is me"
}

Additionally, the Key attribute may incorporate the specially reserved => mapping operand. This functionality enables the dynamic construction of param lists from markers containing an array of strings. These values replace the %s placeholder, thereby generating the final name for each resource.

{
    "Key": "my-param-% => ${USER.roles}",
    "Value": "a"
}

The ${USER.roles} marker returns an array of roles user has (e.g. "[contributor,editor]") and this will dynamically generate a policy with a list of params:

[
    {
        "Key": "my-param-contributor",
        "Value": "a"
    },
    {
        "Key": "my-param-editor",
        "Value": "a"
    }
]

Last but not least, the param can also override any website option that you normally fetch with the get_optionopen in new window or get_site_optionopen in new window WordPress core functions. Just prefix the Key with reserved option: string.

{
    "Param": [
        {
            "Key": "option:users_can_register",
            "Value": 0,
            "Condition": {
                "In": {
                    "${DATETIME.D}": [
                        "Sat",
                        "Sun"
                    ]
                }
            }
        }
    ]
}

The param above overrides the WordPress core option users_can_register and allows registration on the site only during weekdays.

# Value

• Type: Any
• Required

The Value attribute may contain any sort of information. It can be a scalar value or an object. JSON policy does not enforce any constraints on what it may contain.

In the example below, you'll find params that contain a simple string and complex JSON structure and both are valid.

{
    "Param": [
        {
            "Key": "my-string",
            "Value": "Hello World!"
        },
        {
            "Key": "my-object",
            "Value": {
                "top-level": {
                    "phrase": "Hello World!"
                }
            }
        },
    ]
}

The Value property within the context can contain markers that are resolved dynamically and recursively when policies are loaded. For instance, consider the following parameter, which holds an array of user attributes:

{
    "Param": {
        "Key": "UserAttributes",
        "Value": [
            "${USER.first_name}",
            "${USER.last_name}"
            "${USER.user_email}"
        ]
    }
}

By programmatically accessing this parameter, you can retrieve the current user's attributes:

print_r(AAM::api()->getAccessPolicyManager()->getParam('UserAttributes'));

// The result will be something like:
// array(
//    'John',
//    'Smith',
//    'jsmith@mydomain.com'
// )

# Enforce

• Type: Boolean
• Optional

The Enforce is an optional attribute that enforces certain param over other params with exactly the same Key name. It works exactly the same way as the Enforce attribute for the statements and you can refer to its description to learn a bit more.

# Condition

• Type: { Equals: Object, NotEquals: Object, ... }: Object
• Optional

The Condition attribute is the optional attribute and contains a collection of conditions that if met, classifies the param as applicable. This is a good way to determine if the param is applicable within the current executable context.