Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

Configuration Files

Sukarix is configured via .ini files by default, allowing for clear and manageable settings. The configuration load order ensures that settings can be overridden based on the environment.

Configuration Load Order

  1. Base Configuration:

    • config/classes.ini
    • config/default.ini

  2. Additional Configurations:

    • Files listed in the CONFIGS variable, e.g., smtp, notifications, upload. No need to add .ini extension.
    • config/validation.ini (loaded only when a data validation request is initiated).

  3. Environment-Specific Configuration:

    • config/config-<environment>.ini

  4. Routing and Access Control:

    • config/routes.ini
    • config/routes-<environment>.ini
    • config/access.ini or config/access-cli.ini (based on environment).

Note

Dynamic reconfiguration

Configuration changes are automatically reloaded, meaning there is no need to restart any service.

Tip

Automatic .ini Extension Handling

When specifying additional configuration files in the CONFIGS variable, you do not need to include the .ini extension. Sukarix will automatically append .ini to the file name during the loading process. For example, if you set CONFIGS=notifications,smtp,upload, Sukarix will load config/notifications.ini, config/smtp.ini, and config/upload.ini.

Environment Overrides

Any configuration setting can be overridden in the environment-specific .ini file (config/config-<environment>.ini). This allows for tailored configurations depending on whether the application is in development, testing, staging or production.

Environment Variables

A setting that differs per host — and especially a secret — does not belong in a file that is committed. The [environment] section declares which variable stands in for which setting, and the framework applies them after the configuration is loaded:

[environment]
APP_SMTP_HOST     = mailer.smtp.host
APP_SMTP_USERNAME = mailer.smtp.user
APP_SMTP_PASSWORD = mailer.smtp.pw
APP_DB_DSN        = db.dsn

A variable that is unset or empty leaves the configured value alone, so a deployment overrides only what it needs to and the .ini files keep working as defaults.

Tip

Where to declare the section

Put it in the file that owns the settings it maps — mail variables in smtp.ini, database variables in default.ini. The section is read from the merged configuration, so several files may each contribute one.

Default Configuration Example

Here is an overview of the default settings found in default.ini:

  • Global Settings:

    • DEBUG: Stack trace verbosity.
    • PACKAGE: Display name in requests.
    • LOGS: Custom log location.
    • TEMP: Temporary folder for cache and compiled templates.
    • UPLOADS: Directory for file uploads.
    • UI: Paths for user interface files.
    • LOCALES: Location of language dictionaries.
    • ENCODING: Default character encoding.
    • LANGUAGE: Active language.
    • FALLBACK: Fallback language.

  • Cache and Minification:

    • CACHE: Cache configuration.
    • SEED: Cache seed.
    • MINIFY_JS and MINIFY_CSS: Toggle minification.

  • Timezone and Environment:

    • TZ: Timezone setting.
    • application.environment: Current environment.
    • log.session: Log session queries.
    • session.table: Table for session storage.
    • pagination.limit: Default pagination limit.
    • template.default: Default view to render.
    • log.keep: Log retention period.
    • server.host: Host for command-line actions.
    • error.channel: Error notification channel.

  • Security:

    • SECURITY.csrf.enabled: Enable or disable CSRF protection.
    • SECURITY.csrf.expiry: CSRF token expiry time in seconds.
    • SECURITY.stateless.prefixes: Route prefixes served without a session, /api by default. See Session.
    • api.cors.origins: Origins allowed to call a JSON API endpoint. See Building JSON APIs.

  • Logging:

    • log.json: Emit structured JSON log lines to stdout instead of the line-formatted log file. See Logging.

  • Mail:

    • mailer.smtp.timeout: Seconds to wait for the SMTP server, 2 by default.
    • mailer.debugger_name: Name exception reports are sent under. See Emails.

  • ORM:

    • orm.mask_deprecations: Keeps a deprecation in Cortex from ending every request on PHP 8.5. Enabled by default; set to false once Cortex is fixed.