Configuration

Configuration

All configuration in StackCTL lives in the config/ directory. Each file returns a plain PHP array and is loaded during bootstrap, merged into a single config object, and bound to the App container. Values are accessed anywhere in the app using the config() helper with dot notation.

config('app.name')         // → 'StackCTL'
config('database.host')    // → 'localhost'
config('auth.remember_me') // → false
config('mail.from_email')  // → 'hello@example.com'

The first segment is the filename, the rest are keys within that file. Returns null if a key doesn't exist.

config/app.php

General application settings.

return [
    'name'     => 'StackCTL',       // Your application name
    'env'      => 'local',          // 'local' or 'production'
    'timezone' => 'America/Chicago', // PHP timezone string
    'url'      => '',               // Base URL (optional)

    'logo' => [
        'main' => '/public/assets/img/stackctl-logo.svg',
        'icon' => '/public/assets/img/stackctl-icon.svg',
    ],

    'ui' => [
        'tailwind_cdn' => true, // Load Tailwind via CDN
    ],
];

Key settings to know

• env — Controls debug behavior throughout the app. When set to 'local', detailed error messages, stack traces, and exception details are shown on error pages. Set to 'production' before going live — errors are swallowed silently and generic error pages are shown instead.
• timezone — Applied via date_default_timezone_set() during bootstrap. Use any valid PHP timezone string.
• tailwind_cdn — When true, the Tailwind CSS CDN script is injected into the base layout automatically. Set to false if you're using a compiled Tailwind build instead.

config/database.php

MySQL connection settings. These are used by the Database class during bootstrap to establish the shared PDO connection.

return [
    'engine'   => 'mysql',
    'host'     => 'localhost',
    'port'     => '3306',
    'dbname'   => 'your_database',
    'user'     => 'your_user',
    'password' => 'your_password',
];

Update these values to match your local and production environments. The Stack CLI's database commands (db:apply, db:rollback, etc.) also read directly from this file.

config/auth.php

Controls the built-in authentication system — registration, email verification, MFA, remember me, and the permissions map.

return [
    'driver'             => 'local',
    'allow_registration' => true,   // Enable or disable public registration
    'verify_email'       => true,   // Require email verification after register

    // Multi-factor authentication
    'mfa_enabled'            => false,
    'mfa_driver'             => 'both', // 'email', 'app', or 'both'
    'mfa_expiration_minutes' => 5,

    // Remember Me — persistent login via secure cookie
    'remember_me' => false,

    // Permissions map — used by can() helper and can: middleware
    'permissions' => [
        // 'edit'   => ['article' => ['admin', 'editor']],
        // 'delete' => ['article' => ['admin']],
        // 'manage' => ['user'    => ['admin']],
    ],
];

Key settings to know

• allow_registration — Set to false to disable the public registration page entirely. Useful for invite-only or internal apps.
• verify_email — When true, new users receive a verification email and cannot access the app until their email is confirmed. Requires mail configuration.
• mfa_enabled — Enables two-factor authentication. Supports email-based OTP codes ('email'), authenticator apps ('app'), or both. The robthree/twofactorauth package is required for the 'app' driver — install it with php stack packages:install.
• remember_me — When true, a "Remember Me" checkbox appears on the login form. A secure token is stored in the database and a cookie is set in the browser, keeping the user logged in across sessions.
• permissions — Maps actions and resources to the roles allowed to perform them. Used by the can() helper and can: middleware. See the Auth & Middleware doc for full usage.

config/mail.php

SMTP settings for outgoing email. Used by MailService and the built-in auth flows (email verification, password reset, MFA codes). Requires the phpmailer/phpmailer package.

return [
    'host'       => 'smtp.example.com',
    'port'       => '587',
    'encryption' => 'tls',       // 'tls' or 'ssl'
    'username'   => 'you@example.com',
    'password'   => 'your-smtp-password',
    'from_email' => 'hello@example.com',
    'from_name'  => 'My App',
];

You can configure mail settings interactively from the terminal without editing the file directly:

php stack email:config  // guided setup prompt
php stack email:test -to=you@example.com  // send a test email

See the Stack CLI doc for full details on the email commands.

Adding Your Own Config

You can add new config files to the config/ directory and register them in bootstrap/init.php alongside the existing ones.

// In bootstrap/init.php
$config = [
    'app'      => require __DIR__ . '/../config/app.php',
    'database' => require __DIR__ . '/../config/database.php',
    'auth'     => require __DIR__ . '/../config/auth.php',
    'mail'     => require __DIR__ . '/../config/mail.php',
    'billing'  => require __DIR__ . '/../config/billing.php', // your custom file
];

Values are then accessible immediately via config('billing.stripe_key') and so on.