URLs Access

The AAM_Framework_Service_Urls service is responsible for controlling access to WordPress URLs at runtime. It provides a rule-based system to:

• Allow or deny access to URL patterns
• Attach redirect or workflow behaviors when access is denied
• Evaluate access decisions for both authenticated and anonymous users
• Resolve matching rules based on URL path + query parameters
• Provide a unified API for access control enforcement

This service is typically accessed via:

$service = AAM::api()->urls();

# Core Concepts

# URL Schema

A URL schema is any string or array of strings representing:

• A full URL (https://example.xyz/course/lesson-1?tab=video)
• A path-only rule (/course/*)
• A relative WordPress path (/wp-admin/)
• Multiple rules (['/a', '/b', '/c'])

All schemas are normalized internally via:

$this->_normalize_resource_identifier($url_schema)

If invalid, an InvalidArgumentException is thrown.

# 2. Permission Model

Each URL rule is stored as a permission entry:

[
  'effect' => 'allow' | 'deny',
  'redirect' => [ ... ] // optional
]

• allow → explicitly grants access
• deny → blocks access and optionally triggers redirect workflow

# Methods

# allow()

Grants access to one or multiple URL schemas.

public function allow(string|array $url_schema) : bool

# Behavior

• Stores permission with effect = allow
• Removes implicit restrictions by overriding deny rules (via sorting logic)
• Returns true if successfully stored

# Example

$service = AAM::api()->urls();

$service->allow('/dashboard');

// Multiple URLs
$service->allow([
    '/dashboard',
    '/profile',
    '/settings'
]);

# deny() (aka restrict)

Blocks access to URL(s) and optionally defines redirect behavior.

public function deny(string|array $url_schema, array $redirect = null) : bool

# Redirect Configuration

When access is denied, a workflow can be defined:

# Example — Simple restriction

$service->deny('/golden-membership/');

# Example — Login redirect

AAM::api()->urls(
    AAM::api()->visitor()
)->deny('/course/*', [
    'type' => 'login_redirect'
]);

# Example — User-specific redirect

AAM::api()->urls(
    AAM::api()->user('emily@example.xyz')
)->deny('/department-page', [
    'type' => 'url_redirect',
    'redirect_url' => '/department'
]);

# reset()

Removes URL rules.

public function reset(string|array|null $url_schema = null) : bool

# Behavior

• If $url_schema is provided → removes specific rules
• If null → clears all URL permissions for current scope

# Example

$service->reset('/dashboard');

Reset everything:

$service->reset();

# is_denied()

Determines whether a URL is currently blocked.

public function is_denied(string $url) : bool

# Behavior

1. Find matching permission
2. Evaluate:

   $permission['effect'] !== 'allow'
   
3. Apply filter:

   aam_url_is_denied_filter
   
4. Normalize result to boolean

# Example

if ($service->is_denied($_SERVER['REQUEST_URI'])) {
    // Block logic
}

# is_allowed()

Inverse of is_denied().

public function is_allowed(string $url) : bool

# Behavior

return !$this->is_denied($url);

# Example

if ($service->is_allowed('/dashboard')) {
    // show content
}

# get_redirect()

Returns redirect configuration for a denied URL.

public function get_redirect(string $url) : ?array

# Behavior

• If permission exists and has redirect → returns it
• If denied without redirect → returns:

['type' => 'default']

• If no rule → returns null

# Example

$redirect = $service->get_redirect('/checkout');

if ($redirect) {
    AAM_Framework_Utility_Redirect::do_redirect($redirect);
}

# Error Handling

All public methods:

• Wrap execution in try/catch

• Return:

  • bool on success
  • WP_Error on failure (via _handle_error())

# Filters

# aam_url_is_denied_filter

apply_filters(
    'aam_url_is_denied_filter',
    $result,
    $url,
    $permission
);

Allows runtime override of access decision.

# aam_get_permission_by_url_filter

apply_filters(
    'aam_get_permission_by_url_filter',
    $result,
    $url,
    $permissions
);

Allows modification of resolved permission.