Configuration reference

This page is a lookup reference for the config keys used by WebEngine. For the conceptual overview of how config is loaded and used, see Configuration.

Reference structure

The easiest way to document WebEngine config is by section. Each section groups related keys, and each key should be understood in terms of:

• what it controls
• its default value
• when you might want to override it

Main sections

The main sections are:

• app
• router
• view
• logger
• sentry
• session
• database
• security

For the underlying config package, see https://www.php.gt/docs/Config/Home/.

Config section: app

• namespace - default App - the namespace prefix to use when loading classes within your project. This might be your company's name, for example.
• production - default false - set to true when deployed to a production server.
• class_dir - default class - the directory name to use as the PSR-4 root for your application classes.
• service_loader - default ServiceLoader - the class name of your application's service loader, for extending the service container.
• slow_delta default 0.25 - the number of seconds a request takes to trigger a "slow" notice.
• very_slow_delta - default 0.50 - the number of seconds a request takes to trigger a "very slow" warning.
• render_buffer_size - default 1024 - number of bytes to flush in chunks to the browser.

See protected globals.

• globals_whitelist_env - default unset - which $_ENV variables to leave available globally.
• globals_whitelist_server - default unset - which $_SERVER variables to leave available globally.
• globals_whitelist_get default xdebug - which $_GET variables to leave available globally.
• globals_whitelist_post - default unset - which $_POST variables to leave available globally.
• globals_whitelist_files - default unset - which $_FILES variables to leave available globally.
• globals_whitelist_cookies - default unset - which $_COOKIE variables to leave available globally.
• force_trailing_slash default true - true to end requests with a slash, false to end requests without a slash, e.g. www.example.com/test/ vs www.example.com/test.

See Errors and logging#Custom error pages.

• error_page_dir - default page/_error - the directory name to use to contain error pages.

Config section: router

See Routing reference.

• router_file - default router.php - the application router file to load before falling back to the framework router.
• router_class - default AppRouter - the router class name expected within router_file.
• redirect_response_code - default 307 - the HTTP status code used for framework-generated redirects such as trailing-slash normalisation.
• default_content_type - default text/html - the content type used when the router does not set one explicitly.

Config section: view

• component_directory - default page/_component - the directory containing custom HTML components.
• partial_directory - default page/_partial - the directory containing page partials.

Config section: logger

• log_all_requests - default true - log standard requests at the configured logger level.
• log_static_requests - default false - include requests for static files in the request log.
• log_404_to_error_log - default false - when true, 404 responses are additionally written to the error log.
• log_redirects - default false - include redirect responses in the log output.
• debug_to_javascript - default true - when buffering debug output, expose it to the browser-side JavaScript debug stream.
• stderr_level - default error - the minimum log level routed to stderr when using split stdout/stderr logging. Case-insensitive; the local destination's minimum level still applies.
• type - default stdout - comma-separated destinations: stdout, sentry, or sentry,stdout. The local destination retains the stdout/stderr split. The Sentry destination requires the SDK and sentry.dsn.
• level - default debug - one shared minimum severity, or comma-separated minimum severities matching type in order. For example, type=sentry,stdout with level=error,debug sends errors and above to Sentry and debug and above locally. A level count other than one or the destination count throws LoggerConfigurationException. Levels are case-insensitive: debug, info, notice, warning, error, critical, alert, emergency.
• path - default empty - the file path to log to when using a file-based logger target.
• timestamp_format - default Y-m-d H:i:s - PHP date format used when rendering log timestamps.
• log_format - default {TIMESTAMP}\t{USER}\t{LEVEL}\t{MESSAGE}\t{CONTEXT} - the template used to format each log line.
• separator - default \t - the separator token used by the logger formatter.
• newline - default \n - the line ending appended to each log entry.

See Errors and logging#Sending logs to Sentry or GlitchTip for setup, examples and delivery behaviour.

Config section: sentry

• dsn - default empty - the Sentry or GlitchTip project DSN. With the Sentry SDK installed, a nonempty DSN enables automatic exception reporting, independently of logger destinations and severity.
• environment - default empty - an optional environment name, such as staging or production. Surrounding whitespace is trimmed. Missing or blank values leave the SDK default intact: server-provided SENTRY_ENVIRONMENT, otherwise production.

See Errors and logging#Optional Sentry error reporting for installation, captured errors and privacy considerations.

Config section: session

See sessions.

• handler - default Gt\Session\FileHandler - the session handler class to use.
• path - default phpgt/session - storage path passed to the session handler.
• name - default GT - the session name sent in the cookie or URL-based session identifier.
• use_cookies - default true - when true, PHP session IDs are stored in cookies.

Config section: database

See databases.

• driver - default sqlite - the database driver name.
• host - default localhost - the database host name, mainly relevant for networked database drivers.
• schema - default :memory: - the schema or database name. For SQLite, the default is an in-memory database.
• port - default 0 - the database port. A zero value leaves port selection to the driver defaults.
• username - default app_user - the database username.
• password - default app_pass - the database password.
• query_directory - default query - the directory containing SQL query files.
• migration_path - default _migration - the directory containing migration files.
• migration_table - default _migration - the table name used to track applied migrations.
• query_path - default query - the path used when resolving query files.

Config section: security

See security.

• default_headers - default unset - optional semicolon-separated security headers to append to responses.
• csrf_header - default X-CSRF - the header name used to transmit CSRF tokens for refreshing client-side.
• csrf_ignore_path - default empty - a comma-separated list of request paths or path patterns excluded from CSRF checks.
• csrf_max_tokens - default 100 - the maximum number of CSRF tokens retained before older ones are discarded.
• csrf_token_length - default 32 - the generated CSRF token length in bytes.
• csrf_token_sharing - default per-page - whether tokens are generated once per-page or once per-form.

Practical notes

Some keys mainly affect development, such as debug or logging behaviour. Others are only required for production, such as database credentials, session settings, and security-related values.

When in doubt, keep project-level defaults small and override only what the environment genuinely needs to change.

Important

Never store your secret credentials such as API keys or database passwords in version control. Your project's config.ini should only have development-related credentials or empty values stored - secret values should only ever be stored within config.production.ini, placed their manually or via your project's deployment process.

---

Move on to the routing reference page.