Documentation WIP

This is a notepad that I'm scratching down all the documentation points that need organising when I get the time:

• init.php is a special file that you can put into the root of your project to execute before every request. Use it to set up the PHP environment before anything else is executed.
• redirect.csv - the first of the "control files" that can control the way the execution happens.

Redirect control

This component lets you define site-wide redirects in a single file in your project root, applied before the page lifecycle begins. It is designed to be simple to maintain, friendly for editors, and safe by default.

Overview

Place a file named one of the following in your project root:

• redirect.ini
• redirect.csv
• redirect.tsv

The Redirect class automatically discovers and loads the single redirect file using the glob pattern redirect.{csv,tsv,ini}. If more than one file matches, a RedirectException is thrown, as multiple sources would be ambiguous.

Quick start

1. Create redirect.ini in your project root:

/old-path=/new-path

2. Run your application Requests to /old-path will be redirected to /new-path with HTTP 307 by default.

Redirect file formats

• INI
  • Flat (no sections): each line oldURI=newURI uses the default status 307.
  • Sectioned: use numeric status code sections.
  • Section names must be numeric between 301 and 308 inclusive; any non-numeric section causes a RedirectException.

[301]
/moved=/new-location
[303]
/see-other=/somewhere

• CSV
  • Columns: oldURI,newURI[,status]
  • If the third column is present it must be numeric (301–308); otherwise a RedirectException is thrown. If omitted, 307 is used.
• TSV
  • Same as CSV but tab-delimited: oldURI \t newURI [\t status]
  • Same validation rules as CSV apply.

Regex rules (nginx-style)

To define a regex match for the old URI, prefix the pattern with ~.

Example that maps both /shop/cat/item and /shop/dog/thing:

• ~^/shop/([^/]+)/(.+)$ = /newShop/$1/$2 (INI)
• ~^/shop/([^/]+)/(.+)$ , /newShop/$1/$2 (CSV)

The replacement may reference capture groups using $1, $2, etc. Invalid regex patterns result in a RedirectException.

Status codes and validation

The default status code is 307. This is a temporary redirect that preserves POST data, unlike 302 or 303.

Allowed range: 301–308 (inclusive). Values are validated and normalised.

For INI with sections, the section number is the status code; for CSV/TSV, the optional third column is the status.

Non-numeric INI sections and non-numeric third columns in CSV/TSV throw a RedirectException with a message describing the invalid value.

Exceptions and error messages

• Multiple redirect files: "Multiple redirect files in project root".
• Invalid HTTP status code read from a file: "Invalid HTTP status code in redirect file: ".
• Invalid regex pattern: message explains which pattern failed.

How loading and matching works

• Redirect determines the loader from the file extension (INI, CSV, TSV) and populates an internal RedirectMap.
• Literal rules and regex rules are both supported. Matching prefers literal rules first; if no literal match is found, regex rules are evaluated in a deterministic order.
• Only a single redirect file may exist; if none is found, getRedirectUri returns null and execute does nothing.