StaticPHP
 

Documentation

 

Redirections

StaticPHP supports URL redirection, allowing you to automatically redirect users from one page to another. This is particularly useful when moving or renaming pages, ensuring that old URLs continue to work seamlessly.

Note: Redirections apply only to web pages. For redirects involving assets or non-HTML files, you'll need to use alternative methods.

Bulk Redirects

The Bulk Redirects feature in StaticPHP enables you to manage multiple redirects easily using a single file: _bulk_redirects. This file allows you to list all your redirection rules in one place, making it simple to update or add new redirects without modifying your codebase.

Format

Each redirection rule should be placed on a new line. The format consists of two parts:

  1. Old Path: The original URL or path that needs to be redirected.
  2. Destination Path/URL: The target URL or new path that the original URL should point to.

These two parts should be separated by a space.

Example

Here's an example of how your _bulk_redirects file might look:

 /here /there
 /old.html /new.html
 /about /about-us

In the example above:

  • /here will be redirected to /there.
  • /old.html will be redirected to /new.html.
  • /about will redirect to /about-us.

Notes:

  • Ensure that paths in the old URL are relative (without domain or protocol) and use forward slashes /.
  • The destination can be an absolute URL or relative path. If using an absolute URL (e.g., https://example.tld/new), make sure it includes the full URL structure.

This system makes it easy to handle large-scale redirects in bulk, simplifying site maintenance and ensuring a smooth user experience even after restructuring or updating content.

Single Redirections

The Single Redirections feature in StaticPHP allows you to easily redirect from one page to another, either within your site or to an external URL. This is useful in cases where you want to redirect users from an outdated or temporary URL while still preserving the content of the original page in your project source files.

You can define the special metadata key redirect at the top of your page's source file. The value of redirect should be the target path or URL where the page should redirect. StaticPHP will process this metadata and automatically handle the redirection for you, without rendering the original page content.

How It Works

When StaticPHP encounters a page with a redirect key in the metadata, it won't output the page's regular content. Instead, it will generate a response that instructs the browser to perform a redirection to the specified URL or path.

Example

Let's say you have a file named old.html and you want to redirect users to a new page located at https://example.tld/new. You would add the following metadata at the top of the file:

 ---
 redirect: https://example.tld/new
 ---

In this example:

  • The redirect key specifies the target URL: https://example.tld/new.
  • When StaticPHP processes this file, it will not render the content of old.html. Instead, it will generate an HTTP response that tells the browser to redirect to the specified URL.

The user's browser will automatically follow the redirect, and they will be taken to https://example.tld/new.

Notes:

  • The redirect URL can be either an absolute URL (e.g., https://example.tld/new) or a relative URL (e.g., /new).
  • This feature is ideal for temporary redirects or handling legacy URLs.

How Does the Redirection Work?

StaticPHP creates a simple HTML file at the path you specified. This file contains a meta refresh tag that automatically redirects the user to the new destination. This is a well-established technique supported by almost all modern browsers.

The HTML file generated by StaticPHP will include the following structure:

 <!DOCTYPE html>
 <html lang="en">
     <head>
         <meta http-equiv="refresh" content="0; url='https://example.tld/new'" />
         <title>Redirecting...</title>
     </head>
     
     <body>
         <p>If you are not redirected, <a href="https://example.tld/new">click here</a>.</p>
     </body>
 </html>

In this example, the <meta> tag tells the browser to wait 0 seconds before redirecting to the new URL (https://example.tld/new). If, for any reason, the redirection does not work, users can click the provided link to reach the new destination.

Custom Redirection Template

You can specify your own HTML structure for the redirection page by creating a file in the root of your source directory called _redirection_template.html. If this file exists, StaticPHP will use its contents when generating the redirection page, giving you full control over the design, layout, and even the timing of the redirection.

This customization allows you to adjust the timing of the redirection, should you want to delay it for any reason (e.g., to display a message to users before they are redirected).

The following placeholders are available for use in your custom redirection template:

  • $newDestination: The target URL where the user will be redirected.
  • $oldPath: The path from which the user is being redirected.
Example

Here's an example of a custom _redirection_template.html file:

 <!DOCTYPE html>
 <html lang="en">
     <head>
         <meta charset="UTF-8">
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <meta http-equiv="refresh" content="5; url='$newDestination'" />
         
         <title>Redirecting...</title>
     </head>
     
     <body>
         <h1>Redirecting...</h1>
         <p>You are about to be redirected from <b>$oldPath</b> to <b>$newDestination</b>.</p>
         <p>If you are not redirected within 5 seconds, <a href="$newDestination">click here</a>.</p>
     </body>
 </html>

In this example:

  • The $newDestination placeholder is replaced with the URL where the user is being redirected.
  • The $oldPath placeholder is replaced with the path the user is coming from.
  • The redirection is delayed for 5 seconds, as specified by the content="5; url='$newDestination'" attribute in the <meta> tag. You can adjust the number 5 to any number of seconds you want for the delay, or set it to 0 for no delay.

Why Meta Refresh?

The <meta http-equiv="refresh"> tag has been used for automatic redirection for many years and is supported by nearly all browsers. While this method is generally reliable, StaticPHP ensures that if the redirect fails, a clickable link is provided as a backup.