How can I configure a proxy server for outgoing connections?

Issue

Some server setups enforce that all outgoing traffic is routed trough a proxy. This setup is applied to increase the security by restricting what and to whom a connection can be opened.

Resolution

We use an HTTP client which allows to route the traffic through a proxy. However the proxy configuration has to be provided through an environment variable. This environment variable can be defined in different ways:

  1. The environment variable is defined in the server configuration (e.g. in the virtual host configuration of the shop domain).
  2. The environment variable is defined in a .htaccess file located in the shop directory.
  3. The environment variable is defined in some PHP file which is always loaded.

Which solution fits the best depends on the server setup and the way the shop is maintained. The environment variable has to be called PHP_HTTP_CLIENT_PROXY_URL and it has to contain an URL which contains optionally a username and a password. The URL has the following schema:

https://username:[email protected]:port

The username is the login name of the proxy server and the password the corresponding password. The port indicates to which port we have to connect to on the proxy server. The protocol can be either http or https. This depends on the proxy server setup.

We use internally the function stream_socket_client to open the socket. We pass the settings you provide through the environment variable to the function stream_context_create as specified in PHP documentation.

Setup Environment Variable in the Server Configuration

The definition of a environment variable on a web server level depends on the web server. Below you find such a configuration for an Apache 2 web server:

SetEnv PHP_HTTP_CLIENT_PROXY_URL "https://username:[email protected]:port"

The above line should be added within the virtual host configuration which is applied to the shop. This should be set before any rewrite rules. Otherwise the variable may not be set. Important: To use this functionality you must have enabled the Apache module mod_env. Otherwise this will give you an error.

Setup Environment Variable in .htaccess

When an Apache web server is used normally it is possible to use a .htaccess file which may be used to define the environment variable. The following line should be added within the .htaccess before any rewrite rule is applied.

SetEnv PHP_HTTP_CLIENT_PROXY_URL "https://username:[email protected]:port"

This only works when the Apache module mod_env has been enabled in the web server.

Setup Environment Variable in a PHP file

If non of the above method works for you an other option is to use a snippet which can be inserted into a PHP file:

$_SERVER['PHP_HTTP_CLIENT_PROXY_URL'] = "https://username:[email protected]:port"

It is recommended to put the above snippet in a file which you will typically not replace when you update the shopping cart. If the database credentials are stored in a PHP file this may be a good location to put it.

Verification

To verify if the environment variable has been configured correctly you can use the following PHP snippet:

echo $_SERVER['PHP_HTTP_CLIENT_PROXY_URL'];

If this prints the proxy URL the environment variable has been setup correctly.