Configuration

Overview

Flight provides a simple way to configure various aspects of the framework to suit your application's needs. Some are set by default, but you can override them as needed. You can also set your own variables to be used throughout your application.

Clear, layered config (file defaults + environment secrets) also helps AI coding tools: agents learn one place for literals and one place for secrets, instead of inventing $_ENV reads inside controllers.

Understanding

You can customize certain behaviors of Flight by setting configuration values through the set method.

Flight::set('flight.log_errors', true);

In a structured app (including the skeleton), you typically load project settings from app/config/config.php and then apply relevant keys onto the Engine (for example flight.base_url, flight.views.path). You can also inject a small config object into controllers instead of reading globals everywhere—friendlier for tests and for agents following AGENTS.md.

Basic Usage

Flight Configuration Options

The following is a list of all the available configuration settings:

flight.base_url ?string - Override the base url of the request if Flight is running in a subdirectory. (default: null)
flight.case_sensitive bool - Case sensitive matching for URLs. (default: false)
flight.handle_errors bool - Allow Flight to handle all errors internally. (default: true)
- If you want Flight to handle errors instead of the default PHP behavior, this needs to be true.
- If you have Tracy installed, you want to set this to false so Tracy can handle errors.
- If you have the APM plugin installed, you want to set this to true so the APM can log the errors.
flight.log_errors bool - Log errors to the web server's error log file. (default: false)
- If you have Tracy installed, Tracy will log errors based on Tracy configurations, not this configuration.
flight.debug bool - Output detailed error information (exception message, code, and stack trace) in the browser when an error occurs. (default: false)
- Never enable this in production — it leaks internal application details. Use it only for local development or staging.
- When false, a generic 500 Internal Server Error is shown instead. Pair with flight.log_errors to capture errors server-side.
flight.allow_method_override bool - Allow the HTTP method to be overridden via the X-HTTP-Method-Override request header or a _method field in the POST body. (default: true)
- Setting this to false is recommended for applications that do not need HTML-form-based method spoofing, as it prevents clients from forging DELETE or PUT requests through a standard POST form.
- See Security for more details.
flight.views.path string - Directory containing view template files. (default: ./views)
flight.views.extension string - View template file extension. (default: .php; the official skeleton sets this to .twig when using Twig)
flight.content_length bool - Set the Content-Length header. (default: true)
- If you are using Tracy, this needs to be set to false so Tracy can render properly.
flight.v2.output_buffering bool - Use legacy output buffering. See migrating to v3. (default: false)

Loader Configuration

There is additionally another configuration setting for the loader. This will allow you to autoload classes with _ in the class name.

// Enable class loading with underscores
// Defaulted to true
Loader::$v2ClassLoading = false;

Remember that autoloading also depends on folder case matching your namespaces—especially with the skeleton's App\ + app/Controller/ layout.

Project config and `.env` (skeleton pattern)

Flight core does not require .env files. Many apps only use a PHP config array. The official skeleton layers configuration so secrets stay out of git while Runway can still rewrite literal config safely:

.env / real environment — secrets and deploy overrides (gitignored).
app/config/config.php — literal PHP array defaults (copied from config_sample.php). Prefer no $_ENV[...] expressions inside this file: tools like runway config:set may rewrite it as static values and could bake secrets into the file.
Merge at bootstrap — env wins for mapped keys; app code reads a config object or $app->get(), not $_ENV in controllers.

Example shape of config_sample.php / config.php (simplified):

<?php
// Literals only — secrets belong in .env for the skeleton workflow
return [
    'app' => [
        'env' => 'development',
        'debug' => true,
        'base_url' => '/',
        'timezone' => 'UTC',
    ],
    'database' => [
        'driver' => 'sqlite', // or mysql, or '' to disable
        'host' => 'localhost',
        'dbname' => '',
        'user' => '',
        'password' => '',
        'file_path' => __DIR__ . '/../../database.sqlite',
    ],
    // ...
];

# .env.example → .env (skeleton)
APP_ENV=development
APP_DEBUG=true
FLIGHT_BASE_URL=/
DB_DRIVER=sqlite
# DB_PASSWORD=...

This split is deliberate for AI-friendly projects: instructions can say “defaults in config.php, secrets in .env, inject Config / Engine—never invent env access in a controller.” Existing apps can ignore .env entirely and keep a single config file.

Variables

Flight allows you to save variables so that they can be used anywhere in your application.

// Save your variable
Flight::set('id', 123);

// Elsewhere in your application
$id = Flight::get('id');

To see if a variable has been set you can do:

if (Flight::has('id')) {
  // Do something
}

You can clear a variable by doing:

// Clears the id variable
Flight::clear('id');

// Clears all variables
Flight::clear();

Note: Just because you can set a variable doesn't mean you should. Use this feature sparingly. The reason why is that anything stored in here becomes a global variable. Global variables are bad because they can be changed from anywhere in your application, making it hard to track down bugs. Additionally this can complicate things like unit testing. Prefer constructor injection (as in the skeleton + Dice setup) for services and config that controllers need.

Errors and Exceptions

All errors and exceptions are caught by Flight and passed to the error method. if flight.handle_errors is set to true.

The default behavior is to send a generic HTTP 500 Internal Server Error response with some error information.

You can override this behavior for your own needs:

Flight::map('error', function (Throwable $error) {
  // Handle error
  echo $error->getTraceAsString();
});

By default errors are not logged to the web server. You can enable this by changing the config:

Flight::set('flight.log_errors', true);

404 Not Found

When a URL can't be found, Flight calls the notFound method. The default behavior is to send an HTTP 404 Not Found response with a simple message.