Configuration

Introduction

All of BowPHP's configuration files are centralized in the config/ directory. Each file is documented to make customization easier.

Accessing the configuration

Retrieving a value

// Retrieve a value (returns null if absent)
$appName = config('app.name');

// Retrieve an entire file
$appConfig = config('app');

No default value in config()

Unlike app_env(), the config() helper does not have a "default value" parameter. Passing a second argument writes the value to the configuration (see "Modifying a value"). To apply a fallback, use ??:

$timezone = config('app.timezone') ?? 'UTC';

Modifying a value

The second argument of config() is a setter: it writes the value to the in-memory configuration for the duration of the request.

config('view.engine', 'twig');
config('view.extension', '.twig');

Dot notation

Dot notation navigates through the configuration files:

• First segment = file name
• Following segments = nested keys

config/app.php

return [
  'name' => 'My Application',
  'settings' => [
    'debug' => true,
    'cache' => [
      'driver' => 'file',
      'ttl' => 3600
    ]
  ]
];

config('app.name');                    // "My Application"
config('app.settings.debug');          // true
config('app.settings.cache.driver');   // "file"
config('app.settings.cache.ttl');      // 3600

Environment variables

The .env.json file

Bow uses .env.json for sensitive settings and environment-specific variables:

.env.json

{
  "APP_NAME": "My Application",
  "APP_ENV": "development",
  "APP_DEBUG": true,

  "DB_CONNECTION": "mysql",
  "DB_HOST": "localhost",
  "DB_PORT": 3306,
  "DB_DATABASE": "app_db",
  "DB_USERNAME": "root",
  "DB_PASSWORD": "secret",

  "MAIL_HOST": "smtp.example.com",
  "MAIL_PORT": 587,
  "MAIL_USERNAME": "user@example.com",
  "MAIL_PASSWORD": "password"
}

Security

Add .env.json to your .gitignore so you never commit your secrets. Create a .env.example.json as a template.

Retrieving variables

// Retrieve a variable
$dbHost = app_env('DB_HOST');

// With a default value
$dbHost = app_env('DB_HOST', 'localhost');

Nested values

.env.json

{
  "SERVICES": {
    "STRIPE": {
      "KEY": "pk_test_xxx",
      "SECRET": "sk_test_xxx"
    },
    "PAYPAL": {
      "CLIENT_ID": "xxx",
      "SECRET": "xxx"
    }
  }
}

$stripeKey = app_env('SERVICES.STRIPE.KEY');
$paypalId = app_env('SERVICES.PAYPAL.CLIENT_ID');

Reusing variables

.env.json

{
  "BASE_URL": "https://api.example.com",
  "WEBHOOKS": {
    "PAYMENT": "${BASE_URL}/webhooks/payment",
    "ORDER": "${BASE_URL}/webhooks/order"
  }
}

app_env('WEBHOOKS.PAYMENT');
// https://api.example.com/webhooks/payment

File format

Single format: JSON

Bow loads only the .env.json format. The classic KEY=VALUE format (dotenv) is not supported by Bow\Support\Env — Env::configure() calls json_decode() directly on the file.

If you are coming from another framework and need the .env format, convert your variables to JSON, or add your own loader.

Configuration files

File	Description
app.php	General configuration (name, timezone, paths, debug)
database.php	Database connections
cache.php	Cache configuration
session.php	Sessions (driver, lifetime, cookies)
storage.php	File storage
mail.php	Email configuration
view.php	Template engine
queue.php	Queue
auth.php	Authentication
security.php	CORS, security headers
translate.php	Internationalization

The app.php configuration

config/app.php

return [
  // Application name
  'name' => app_env('APP_NAME', 'Bow Application'),

  // Automatic CSRF protection
  'auto_csrf' => (bool) app_env('APP_AUTO_CSRF', true),

  // URL prefix (e.g. '/api')
  'root' => app_env('APP_URI_PREFIX', ''),

  // Timezone
  'timezone' => 'Africa/Abidjan',

  // Paths
  'env_file' => realpath(__DIR__ . '/../.env.json'),
  'frontend_path' => dirname(__DIR__) . '/assets',
  'seeder_path' => dirname(__DIR__) . '/seeders',
  'public_path' => dirname(__DIR__) . '/public',
  'storage_path' => dirname(__DIR__) . '/var/storage',

  // Debug mode: development | production
  'debug' => app_env('APP_ENV', 'development'),

  // Custom error handler
  'error_handle' => \App\Exceptions\ErrorHandle::class,

  // Display error traces in JSON
  'error_trace' => true,
];

Custom helpers

Add your custom functions in config/helpers.php:

config/helpers.php

<?php

if (!function_exists('format_price')) {
  function format_price(float $price, string $currency = '€'): string
  {
    return number_format($price, 2, ',', ' ') . ' ' . $currency;
  }
}

if (!function_exists('slugify')) {
  function slugify(string $text): string
  {
    return strtolower(trim(preg_replace('/[^A-Za-z0-9-]+/', '-', $text), '-'));
  }
}

Documentation

See the helpers documentation for all available functions.

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.