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

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.

Debug timer

Debug timer

The debug timer is for measuring elapsed time within the request lifecycle.

Behavior:

• On construction, records the start time.
• Call stop() to record the end time.
• Call getDelta() to retrieve the elapsed time in seconds (float).

Testability:

• Accepts an optional Closure $timeGetter to supply the current time.
• By default, this calls microtime(true).

Autoloading project classes

The Dispatcher sets up the AppAutoloader class. This autoloader is only necessary if Composer's PSR-4 autoloader isn't set up in the project's composer.json.

To set up PSR-4 autoloading in composer.json, add an "autoload" section with "psr-4" mapping your namespace prefix to the directory containing your classes:

{
    "autoload": {
        "psr-4": {
            "MyApp\\": "src/"
        }
    }
}

When Composer's autoloader is properly configured and generated via "composer dump-autoload", it will handle class loading before this autoloader is called, making this class effectively inactive.

Composer's autoloader is preferred for its performance optimisations and efficient class map caching. This fallback autoloader ensures developers can still work on the project during initial setup or when Composer isn't fully configured - exactly when maintaining momentum is most crucial in a project.