Platform.sh User Documentation

Redirects

Upsun Beta

Access our newest offering - Upsun!

Get your free trial by clicking the link below.

Get your Upsun free trial

Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time.

You can manage redirection rules on your Platform.sh projects in two different ways, which we describe here. If neither of these options satisfy your redirection needs, you can still implement redirects directly from within your application, which if implemented with the appropriate caching headers would be almost as efficient as using the configuration options provided by Platform.sh.

Whole-route redirects Anchor to this heading

Using whole-route redirects, you can define very basic routes in your .platform/routes.yaml file whose sole purpose is to redirect. A typical use case for this type of route is adding or removing a www. prefix to your domain, as the following example shows:

https://{default}/:
    type: redirect
    to: https://www.{default}/

Partial redirects Anchor to this heading

In the .platform/routes.yaml file you can also add partial redirect rules to existing routes:

https://{default}/:
    # ...
    redirects:
        expires: 1d
        paths:
            '/from':
                to: 'https://example.com/'
            '^/foo/(.*)/bar':
                to: 'https://example.com/$1'
                regexp: true

This format is richer and works with any type of route, including routes served directly by the application.

Two keys are available under redirects:

Key Required Description
expires No The duration the redirect is cached. Examples of valid values include 3600s, 1d, 2w, 3m.
paths Yes The paths to be redirected

Each rule under paths is defined by a key describing:

  • The expression to match against the request path
  • A value object describing both the destination to redirect to, with detail on how to handle the redirection

The value object is defined with the following keys:

Key Required Default Description
to Yes n/a A relative URL - '/destination', or absolute URL - 'https://example.com/'.
regexp No false Specifies whether the path key should be interpreted as a PCRE regular expression. If you use a capturing group, the replace field ($1) has to come after a slash (/). More information.
prefix No true, but not supported if regexp is true Specifies whether both the path and all its children or just the path itself should be redirected. More information.
append_suffix No true, but not supported if regexp is true or if prefix is false Determines if the suffix is carried over with the redirect. More information.
code No n/a HTTP status code. Valid status codes are 301, 302, 307, and 308. Defaults to 302. More information.
expires No Defaults to the expires value defined directly under the redirects key, but can be fine-tuned. The duration the redirect is cached for. More information.

To set up partial redirects, you can use regular expressions (regexp).
Alternatively, and in many cases, you can use the prefix and/or append_suffix keys to achieve the same results.
Here are some examples to illustrate this and help you choose a method for your partial redirects:

Consider this regexp redirect:

'^/from(/.*|)$':
    regexp: true
    to: https://example.com/to$1

It achieves the same result as this basic redirect:

'/from':
    to: https://example.com/to 

Consider this redirect using prefix:

'/from':
    to: https//example.com/to
    prefix: false

It achieves the same result as this regexp redirect:

'^/from$':
    regexp: true
    to: https://example.com/to

Consider this redirect using append_suffix:

'/from':
    to: https//example.com/to
    append_suffix: false

It achieves the same result as this regexp redirect:

'^/from(/.*|)$':
    regexp: true
    to: https://example.com/to

Redirects using regular expressions Anchor to this heading

You can use regular expressions to configure your redirects.

In the following example, a request to https://example.com/foo/a/b/c/bar redirects to https://example.com/a/b/c:

https://{default}/:
    type: upstream
    # ...
    redirects:
        paths:
            '^/foo/(.*)/bar':
                to: 'https://example.com/$1'
                regexp: true

The following special arguments in the to statement are available when regexp is set to true:

  • $is_args evaluates to ? or empty string
  • $args evaluates to the full query string if any
  • $arg_foo evaluates to the value of the query parameter foo
  • $uri evaluates to the full URI of the request.

Redirects using prefix and append_suffix Anchor to this heading

Instead of using regular expressions to configure your redirects, you might want to use the prefix and append_suffix keys.

When set to true, which is their default value, prefix and append_suffix are equivalent. For example:

https://{default}/:
    type: upstream
    # ...
    redirects:
        paths:
            '/from':
                to: 'https://{default}/to'
                prefix: true
https://{default}/:
    type: upstream
    # ...
    redirects:
        paths:
            '/from':
                to: 'https://{default}/to'
                append_suffix: true

With both configurations:

  • /from redirects to /to
  • /from/some/path redirects to /to/some/path

However, when set to false, prefix and append_suffix behave differently. For example, with the following configuration:

https://{default}/:
    type: upstream
    # ...
    redirects:
        paths:
            '/from':
                to: 'https://{default}/to'
                prefix: true

A request to /from/ redirects to /to/some/path, but a request to /from/some/path does not.

And with the following configuration:

https://{default}/:
    type: upstream
    # ...
    redirects:
        paths:
            '/from':
                to: 'https://{default}/to'
                append_suffix: false

A request to /from/some/path (and any path after /from) redirects to just /to.

Further examples Anchor to this heading

Using codes Anchor to this heading

In the following example using the codes key:

https://{default}/:
    type: upstream
    # ...
    redirects:
        paths:
            '/from':
                to: 'https://example.com/'
                code: 308
            '/here':
                to: 'https://example.com/there'

Redirects from /from use a 308 HTTP status code, but redirects from /here default to 302.

Using expires Anchor to this heading

The expires key defaults to the expires value defined directly under the redirects key. However, at this level the expiration of individual partial redirects can be fine-tuned:

https://{default}/:
    type: upstream
    # ...
    redirects:
        expires: 1d
        paths:
            '/from':
                to: 'https://example.com/'
            '/here':
                to: 'https://example.com/there'
                expires: 2w

In the above example, redirects from /from are set to expire in one day, but redirects from /here are set to expire in two weeks.

Application-driven redirects Anchor to this heading

If neither whole-route or partial redirects satisfy your redirection needs, you can still implement redirects directly in your application. If sent with the appropriate caching headers, this is nearly as efficient as implementing the redirect through one of the two configurations described above. Implementing application-driven redirects depends on your own code or framework and is beyond the scope of this documentation.

Query-strings based redirect are unsupported Anchor to this heading

Platform.sh does not support redirects based on query strings.

If you want to redirect based on query strings, this logic has to be implemented by your application.

Is this page helpful?