Skip to content

Transition request blocks from PHP to the VIP Dashboard

Requests that are blocked with the VIP_Request_Block utility class in PHP are blocked at the origin, not at the edge cache servers (load balancer). If a cached version of the requested content exists at the edge, the request will not reach the origin and the VIP_Request_Block will be ineffective.

To block requests at the edge—before the request reaches origin—use the User Agent Restrictions and IP Restrictions features in the VIP Dashboard. Because blocking at the edge does not require code execution, request blocks that are configured in the VIP Dashboard are handled more quickly and reduce the overall load on an application.

An application that has existing request blocks in code using VIP_Request_Block can take steps to migrate those configurations to the User Agent Restrictions and IP Restrictions features in the VIP Dashboard.

Prerequisites

To edit the User Agent of IP Restriction rules for an environment in the VIP Dashboard, a user must have at minimum an App admin role for that application or an Org admin role.

To edit vip-config.php, a user must have at minimum Write permissions to an application’s wpcomvip GitHub repository, or—if using Custom Deployments—the repository where application code is developed.

Step 1: Identify existing implementations of VIP_Request_Block

To transition request blocks from an application’s codebase to the VIP Dashboard, all existing request block configurations must be identified and documented. Identified instances of the VIP_Request_Block class in the codebase

  1. Search for implementations of the class throughout all files in the repository. Requests that are blocked with the VIP_Request_Block class should be located in vip-config/vip-config.php, but it is possible that code using the class exists elsewhere.
  2. For each located instance of VIP_Request_Block, identify if it is used for restricting requests based on IP addresses or User Agent strings.
  3. Document every blocked IP Address and User Agent, but do not make any updates to the code. This documentation is necessary for later steps in the transition process.

Examples of request blocks in code

Refer to “Block unwanted origin requests with PHP” for additional examples of other possible VIP_Request_Block configurations in code.

// Example VIP_Request_Block::ip( string $value );
if ( class_exists( 'VIP_Request_Block' ) ) {
   VIP_Request_Block::ip( '13.37.13.37' );
   VIP_Request_Block::ip( '13.37.13.38' );
}
// Example VIP_Request_Block::ua( string $user_agent );
if ( class_exists( 'VIP_Request_Block' ) ) {
   VIP_Request_Block::ua( 'SuspiciousBot/1.1' );
   VIP_Request_Block::ua( 'AnotherBot/2.1' );
}
// Example VIP_Request_Block::ua_partial_match( string $user_agent_substring );
// Will match and block for:
// 	- SuspiciousBot/1.1
// 	- SomewhatSuspiciousBot/1.8 - https://example.com/robot-policy
if ( class_exists( 'VIP_Request_Block' ) ) {
   VIP_Request_Block::ua_partial_match( 'SuspiciousBot/' );
}

Step 2: Plan a strategy for restricting requests

It is possible to simultaneously apply restrictions to User Agents, IP addresses, and other methods of controlling requests. As each restriction method is added, ensure that the result of the blocking actions of all active restrictions work as expected. It is possible for the interaction between multiple restriction methods to inadvertently block wanted requests or to fail to block unwanted requests.

Other considerations:

  • User Agent restrictions are particularly useful for requests from a specific service that identifies itself, but where a specific list of IP addresses are not known.
  • IP restrictions can be in the form of an “IP Allow List”, allowing only a certain set of IP addresses access to an application, or an “IP Deny List”, denying access to an application based on a specified list of IP addresses.
  • Classless Inter-Domain Routing (CIDR) IP address notations are supported by IP Restrictions to provide more flexibility in defining IP ranges.

Because there is a large number of configuration options, it is important to consider how restriction rules might overlap and intersect with one another before implementing request restrictions in the VIP Dashboard.

Step 3: Configure restrictions in the VIP Dashboard

Restrictions by IP address or User Agent must be configured in the VIP Dashboard before instances of VIP_Request_Block can be removed from an application’s codebase. Having request blocks temporarily active in both the VIP Dashboard and in code prevents unwanted requests from reaching the application during the transition.

Additionally, configurations in the VIP Dashboard are environment-specific. Ensure that all necessary restrictions by IP address or User Agent are configured in the VIP Dashboard for each environment before updating application code.

To configure restrictions in the IP Address Restrictions or the User Agent Restrictions panels, refer to the blocked IP address(es) and User Agent(s) that were documented in Step 1.

  1. Navigate to the VIP Dashboard.
  2. Select an environment from the environment dropdown located at the top of the VIP Dashboard navigation menu to which these restrictions will apply.
  3. Select “Security Controls” from the sidebar navigation at the left of the screen.
  4. Select “IP Restrictions” from the submenu.
  5. Select the radio option for the type of IP restriction (“IP Allow List” or an “IP Deny List”) that is most similar to the IP restriction that is currently configured in the application codebase.
  6. Select the button labeled “+ Add” to enter the form editor dialog.
  7. Enter one ore more IP addresses to the field labeled “IP Address(es)“. Each entry must be added to a new line in the field.
  8. Optional: Add contextual information about the group of entries in the text field labeled “Notes“. The content added to this field will apply to all of the entries that are currently being edited.
  9. Select the button labeled “Add” to save the added configurations.

The updated configurations typically take up to 10 minutes to take effect.

Refer to “IP Restrictions” for additional information about blocking requests by IP address.

  1. Navigate to the VIP Dashboard.
  2. Select an environment from the environment dropdown located at the top of the VIP Dashboard navigation menu to which these restrictions will apply.
  3. Select “Security Controls” from the sidebar navigation at the left of the screen.
  4. Select “User Agent” from the submenu.
  5. Select the button labeled “+ Add” to enter the form editor dialog titled “Add User Agent group“.
  6. Select a condition (i.e. either “Contains” or “Equals”) for the rule from the dropdown menu labeled “Condition“.
  7. Enter the identifier string value for the User Agent header value (full or partial) to which the rule should be applied.
  8. Optional: Add contextual information about the group of rules in the text field labeled “Notes“. The content added to this field will apply to all of the rules that are currently being edited.
  9. Select the button labeled “Add” to save the added rule configurations.

The updated configurations typically take up to 10 minutes to take effect.

Refer to “User Agent Restrictions” for additional information about blocking requests by User Agent.

Step 4: Validate the VIP Dashboard configurations

The updated restriction configurations in the VIP Dashboard must be validated before instances of VIP_Request_Block in the codebase can be removed.

If any of the validation steps fail, verify that all of the updated configurations in the VIP Dashboard are correct. Also allow for the updated configurations to take up to 10 minutes to take effect.

If it has been confirmed that all updated configurations in the VIP Dashboard are correct, but they are unable be validated and not working as expected, request assistance from VIP Support before removing the VIP_Request_Block code.

  1. Make a request to the site from an allowed IP address and confirm that the site successfully loads.
  2. Make a request to the site from a blocked IP address and confirm that a 403 HTTP status response is returned, and that the response does not include cache-related headers such as x-cache.
  1. Make a request to the site using a blocked User Agent. In a terminal window on the user’s local machine, run a command with the format:
curl -A "<user-agent>" https://<environment-domain>/ -I

In this example command, a user checks if the User Agent BadBot is successfully blocked from the site example.com:

curl -A "BadBot" https://example.com/ -I
  1. Ensure that the response for the cURL command does not include cache-related headers such as x-cache.

Step 5: Remove implementations of VIP_Request_Block

After it has been confirmed that the configurations in the VIP Dashboard work as expected, request blocks that were implemented in code with the VIP_Request_Block class can be removed—or commented out—from vip-config.php or other files.

The updated code can then be deployed to the application environments that have restrictions successfully configured in the VIP Dashboard.

Last updated: July 10, 2025