Configuration

ZephyrPHP uses environment variables and PHP configuration files for flexible, secure configuration management. Configure once, deploy anywhere.

Environment Configuration

ZephyrPHP uses the .env file for environment-specific configuration. This file should never be committed to version control as it contains sensitive information like encryption keys and database credentials.

Environment File Structure

The .env.example file in the starter template shows all available environment variables:

# Application
APP_NAME=ZephyrPHP
APP_DEBUG=true
ENV=dev

# Security (Generate with: php craftsman key:generate)
APP_KEY=

# Views
VIEWS_PATH=/pages

# Database (optional, requires zephyrphp/database module)
# DB_CONNECTION=pdo_mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=zephyrphp
# DB_USERNAME=root
# DB_PASSWORD=

Accessing Environment Variables

Use the env() helper function to retrieve environment variables:

<?php

// Get an environment variable
$debug = env('APP_DEBUG');

// With a default value
$timezone = env('APP_TIMEZONE', 'UTC');

// Boolean values are automatically converted
$debug = env('APP_DEBUG', false); // Returns true/false, not "true"/"false"

Common Environment Variables

Configuration Files

Configuration files are stored in the config/ directory. Each file returns a PHP array of configuration values that can reference environment variables using env().

Available Configuration Files

Application Configuration

The config/app.php file contains core application settings:

<?php

return [
    // Application Name
    'name' => env('APP_NAME', 'ZephyrPHP'),

    // Environment (dev, staging, production)
    'env' => env('ENV', 'dev'),

    // Debug Mode (show detailed errors)
    'debug' => env('APP_DEBUG', true),

    // Application URL
    'url' => env('APP_URL', 'http://localhost'),

    // Default Timezone
    'timezone' => env('APP_TIMEZONE', 'UTC'),

    // Default Locale
    'locale' => env('APP_LOCALE', 'en'),

    // Encryption Key (generated by php craftsman key:generate)
    'key' => env('APP_KEY', ''),
];

Module Configuration

The config/modules.php file controls which modules are loaded. Only enabled modules are loaded, keeping your application lean and fast.

<?php

return [
    // Core Modules (Always Available)
    'session' => true,      // Session management, flash messages, CSRF
    'validation' => true,   // Input validation (40+ rules)
    'view' => true,         // Twig template rendering

    // Optional Modules (Require Installation)
    'database' => false,      // Doctrine ORM (install: php craftsman add database)
    'auth' => false,          // Authentication (install: php craftsman add auth)
    'authorization' => false, // Gates & Policies (install: php craftsman add authorization)
    'cache' => false,         // Caching (install: php craftsman add cache)
    'mail' => false,          // Email (install: php craftsman add mail)
    'queue' => false,         // Background jobs (install: php craftsman add queue)
];

Exception Configuration (Optional)

The config/exceptions.php file allows you to customize error messages, especially useful for database validation errors:

<?php

return [
    'database' => [
        'unique' => 'The {field} has already been taken.',
        'not_null' => 'The {field} field is required.',
        'foreign_key' => 'This {field} is associated with other records.',

        // Field-specific overrides
        'unique:email' => 'This email address is already registered.',
        'unique:username' => 'This username is already taken.',
    ],
];

Accessing Configuration Values

Use the config() helper to retrieve configuration values using dot notation:

<?php

// Get a config value
$appName = config('app.name');

// With a default value
$debug = config('app.debug', false);

// Check if a module is enabled
$hasDatabase = config('modules.database', false);

Application Key

The APP_KEY is a 32-byte base64-encoded key used for encryption, hashing, and security. It's critical for your application's security.

Generating the Application Key

php craftsman key:generate

This command:

• Generates a secure 32-byte random key
• Base64-encodes it with base64: prefix
• Updates your .env file automatically

Views Configuration

Configure the template directory path with VIEWS_PATH:

# Default: /pages (relative to project root)
VIEWS_PATH=/pages

# Custom: use a different directory
VIEWS_PATH=/resources/views

This tells ZephyrPHP where to find your Twig templates. The path is relative to your project root.

Environment-Specific Configuration

Use different .env files for different environments:

Development (.env)

APP_DEBUG=true
ENV=dev
APP_URL=http://localhost:8000

Production (.env.production)

APP_DEBUG=false
ENV=production
APP_URL=https://myapp.com

Staging (.env.staging)

APP_DEBUG=true
ENV=staging
APP_URL=https://staging.myapp.com

Configuration Best Practices

1. Use Environment Variables for Sensitive Data

Always use .env for:

• Database credentials
• API keys and secrets
• Encryption keys
• Third-party service credentials

2. Keep Configuration Files Simple

Configuration files should only contain configuration, not business logic.

<?php

return [
    'name' => env('APP_NAME', 'ZephyrPHP'),
    'debug' => env('APP_DEBUG', false),
];

<?php

// Don't put business logic in config files
return [
    'users' => User::all(), // ❌ Database query
    'settings' => calculateSettings(), // ❌ Function call
];

3. Use config() in Application Code

Never use env() directly in controllers, models, or other application code. Always use config():

<?php

class UserController extends Controller
{
    public function index()
    {
        $appName = config('app.name'); // ✅ Use config()
    }
}

<?php

class UserController extends Controller
{
    public function index()
    {
        $appName = env('APP_NAME'); // ❌ Don't use env()
    }
}

4. Validate Required Configuration

Ensure required configuration values are set:

<?php

// In bootstrap/app.php or a service provider
if (empty(config('app.key'))) {
    throw new RuntimeException('Application key not set. Run: php craftsman key:generate');
}

Debugging Configuration

To see all loaded configuration values, use dd() or dump() in debug mode:

<?php

// Dump all app config
dump(config('app'));

// Dump all config
dd(config());

Next Steps

Now that you understand configuration:

• Learn about the Directory Structure
• Explore Routing to define routes
• Understand Views for templating