Rewrite rules

Yussuf Khalil edited this page Aug 27, 2013 · 4 revisions

Some parts of this document only apply to Pancake 1.5 or newer.

Rewriting URIs can be useful for search engine optimization and is even required by some scripts. Therefore, here is a short explanation on how rewrite works in Pancake.

Basics

Rewrite rules can be applied to any vHost. To add a rule simply add the following lines to your vHost configuration:

rewrite:
  - <rule>
  - <rule2>
  - <...>

RegExs are normal PREGs ( Perl compatible RegEx ), like the ones you would give the preg_*() functions in PHP. Most RegExs written for nginx should work with Pancake too (probably you'll only have to add delimiters at the beginning and at the end of the RegEx), while rules for Apache usually aren't compatible.

Please note that RegEx rules are applied in the order they're configured.

There are two types of rewrite settings:

Conditional settings

Conditional settings allow rule application only if the conditions are met.

location

By setting location you can limit the rule to specific paths. For example, location: /abc/ will cause Pancake only to apply the rule if the path is at least /abc/. Paths like /abc/xyz/ will also be allowed, while /ABC/ would be invalid.

if

if can be set to a RegEx that will be matched against the URI.

ifNot

ifNot works the same way as if, but will execute the rewrite rule only if the RegEx does not match the URI.

precondition

precondition only allows the values 404 and 403. If set to 404, Pancake will only apply the rewrite rule if the requested file does not exist. 403 causes Pancake to apply the rule if the file exists and is not readable.

TLS

Setting TLS to true will apply the rewrite rule only on secure connections, false can be used to check for unsecure connections.

HTTPMethod

Will check for specific HTTP methods when set. Can be either a string or an array of multiple values.

MIMEType

Can be used to check wether the requested file has a specific MIME type. Can be either a string or an array of multiple values.

Rule settings

Rule settings control what happens to the URI if all conditions are met.

headers

headers allows sending an unlimited amount of HTTP header name-value-pairs.

pattern & replace

pattern and replace are RegExs that can be used to replace matches of pattern in the URI with replace.

destination

destination allows setting a full URI that the client will be redirected to.

exception

exception can be set to the value of an HTTP answer code.

exceptionMessage

exceptionMessage allows setting a custom message for the exception that will be shown on the exception page. The default value for exceptionMessage is The server was unable to process your request.

pathInfo

pathInfo can be set to a RegEx consisting of two groups. The RegEx will be used to split the URI into the actual file path and the CGI PATH_INFO.

FastCGI

Forces the usage of a specific FastCGI configuration on a request. Value is FastCGI configuration name.

DisableAccessChecks

Can be used to disable file access checks. Requires FastCGI setting to be set.

UseClientPath

Apart from these conditional and action settings, UseClientPath can be used to tell the rewrite engine to run all settings to use the path provided by the client instead of the already rewritten path.

Examples

rewrite:
  - location: /user/
    pattern: ~^/user/(.*)$~
    replace: /user.php?id=$1

would rewrite the URI /user/1 to /user.php?id=1.

rewrite:
  - precondition: 404
    destination: http://google.com/

would redirect every user requesting a non-existent file to Google.

rewrite:
  - location: /doNotOpen/
    exception: 401
    exceptionMessage: "You are not allowed to request this path."

would send 401 Unauthorized to every user requesting a file inside /doNotOpen/.

rewrite:
  - headers:
      X-TimeZone: "Europe/Berlin"

would add the header X-TimeZone: Europe/Berlin to every answer.

rewrite:
  - pathInfo: ~^((?U).+\.php)(/?.+)$~

would rewrite paths like /index.php/somePath/ to /index.php and set PATH_INFO (can be read in PHP via $_SERVER['PATH_INFO']) to /somePath/.

rewrite:
  - HTTPMethod:
      - OPTIONS
      - TRACE
    exception: 405

would disallow OPTIONS and TRACE requests on this vHost.