#Довідник з конфігурації

Lift налаштовується через змінні оточення (завантажувані з .env) та/або внутрішньопроцесний масив, що передається у $app->config([...]).

Порядок завантаження (від найвищого пріоритету до найнижчого):

1. Реальні змінні оточення, уже встановлені в оболонці / на сервері
2. Значення, завантажені з .env через $app->loadEnv(path)
3. Значення, задані в PHP-масивах конфігурації через $app->config([...])

#Завантаження

$app = new App();
$app->loadEnv(__DIR__ . '/../.env');   // завантажує .env у $_ENV / putenv()
$app->config([                         // необов’язкові перевизначення масивом
    'app.name' => 'My App',
    'app.env'  => 'production',
]);

Читайте значення будь-де через Env::string() / Env::int() / Env::bool():

use Lift\Config\Env;

$dsn  = Env::string('DB_URL');
$port = Env::int('PORT', 8080);   // за замовчуванням 8080
$flag = Env::bool('FEATURE_X');   // null, якщо відсутнє

#Застосунок

APP_NAME="My Blog"
APP_ENV=local
APP_DEBUG=true
APP_KEY=base64:...32-byte-random-key...
APP_URL=https://myblog.example.com

$app->debug(['enabled' => Env::bool('APP_DEBUG', false)]);
$app->loadEnv(__DIR__ . '/../.env');
echo $app->environment(); // → 'local'

#Масове завантаження каталогу конфігурації

$app->configure(string $directory) читає кожен PHP- і YAML-файл у папці та реєструє кожен під ключем, рівним імені файлу (без розширення). Це повторює класичну угоду Laravel:

config/
  app.php       → configuration()->get('app.name')
  database.php  → configuration()->get('database.host')
  cache.php     → configuration()->get('cache.driver')

// bootstrap/app.php
$app = new App();
$app->loadEnv(__DIR__ . '/../.env');
$app->configure(__DIR__ . '/../config');   // завантажити кожен файл у config/

Приклад config/database.php:

<?php
use Lift\Config\Env;

return [
    'driver'   => Env::string('DB_CONNECTION', 'sqlite'),
    'host'     => Env::string('DB_HOST', '127.0.0.1'),
    'port'     => Env::int('DB_PORT', 3306),
    'database' => Env::string('DB_DATABASE', 'storage/db.sqlite'),
    'username' => Env::string('DB_USERNAME', ''),
    'password' => Env::string('DB_PASSWORD', ''),
];

Читання значення будь-де:

$driver = $app->configuration()->get('database.driver', 'sqlite');

configure() виконує рекурсивне злиття, тому багаторазовий виклик (наприклад, завантаження базової конфігурації, а потім накладання перевизначень під конкретне оточення) безпечний:

$app->configure(__DIR__ . '/../config');
$app->configure(__DIR__ . "/../config/{$app->environment()}");  // накладає local/ або testing/

#Методи-скорочення App

App надає зручні аксесори для найчастіше впроваджуваних сервісів:

$app->router();           // Lift\Routing\Router      — кеш маршрутів, генерація URL
$app->db();               // Lift\Database\Connection  — потребує попередньої прив’язки singleton
$app->logger();           // Lift\Log\Logger           — потребує попередньої прив’язки singleton
$app->events();           // Lift\Events\EventDispatcher — потребує попередньої прив’язки singleton
$app->configuration();    // Lift\Config\Config        — живий репозиторій конфігурації (усі завантажені значення)

// Надіслати відповідь вручну (корисно в CLI-обгортках, бенчмарках)
$response = $app->handle($request);
$app->send($response);

db(), logger() і events() делегують у $app->container()->make(ClassName::class). Вони викидають ContainerException, якщо викликати їх до прив’язки сервісу.

#База даних

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=root
DB_PASSWORD=secret

$dsn = match (Env::string('DB_CONNECTION', 'sqlite')) {
    'mysql'  => sprintf('mysql:host=%s;port=%s;dbname=%s;charset=%s',
                    Env::string('DB_HOST', '127.0.0.1'),
                    Env::string('DB_PORT', '3306'),
                    Env::string('DB_DATABASE'),
                    Env::string('DB_CHARSET', 'utf8mb4')),
    'pgsql'  => sprintf('pgsql:host=%s;port=%s;dbname=%s',
                    Env::string('DB_HOST', '127.0.0.1'),
                    Env::string('DB_PORT', '5432'),
                    Env::string('DB_DATABASE')),
    default  => 'sqlite:' . Env::string('DB_DATABASE', 'storage/database.sqlite'),
};
$db = new Connection($dsn, Env::string('DB_USERNAME'), Env::string('DB_PASSWORD'));
$app->instance(Connection::class, $db);

#Сесія

SESSION_DRIVER=file
SESSION_PATH=storage/sessions
SESSION_LIFETIME=7200
SESSION_COOKIE=myapp_session

$store = match (Env::string('SESSION_DRIVER', 'file')) {
    'database'  => new DatabaseSessionStore($db, Env::string('SESSION_TABLE', 'sessions')),
    'redis'     => new RedisSessionStore($redis),
    'memcached' => new MemcachedSessionStore($memcached),
    'array'     => new ArraySessionStore(),
    default     => new FileSessionStore(Env::string('SESSION_PATH', 'storage/sessions')),
};
$session = new Session(
    $store,
    lifetime:   Env::int('SESSION_LIFETIME', 7200),
    cookieName: Env::string('SESSION_COOKIE', 'lift_session'),
);
$app->use(new SessionMiddleware($session));

#Кеш

CACHE_DRIVER=redis
CACHE_PREFIX=myapp_
CACHE_HMAC_SECRET=change-me-to-32-random-bytes

$cache = match (Env::string('CACHE_DRIVER', 'array')) {
    'redis' => new RedisCache(
        $redis,
        Env::string('CACHE_PREFIX', 'lift_'),
        secret: Env::string('CACHE_HMAC_SECRET') ?? throw new \RuntimeException('CACHE_HMAC_SECRET is required'),
    ),
    default => new ArrayCache(),
};
$app->instance(CacheInterface::class, $cache);
$app->instance(\Psr\SimpleCache\CacheInterface::class, new Psr16Adapter($cache));

#Черга

QUEUE_DRIVER=redis
QUEUE_DEFAULT=default
QUEUE_SECRET=change-me-to-32-random-bytes

$queue = match (Env::string('QUEUE_DRIVER', 'sync')) {
    'redis' => new RedisQueue($redis, secret: Env::string('QUEUE_SECRET') ?? throw new \RuntimeException('QUEUE_SECRET is required')),
    'amqp'  => new AmqpQueue([
                   'host'     => Env::string('RABBITMQ_HOST', 'localhost'),
                   'port'     => Env::int('RABBITMQ_PORT', 5672),
                   'user'     => Env::string('RABBITMQ_USER', 'guest'),
                   'password' => Env::string('RABBITMQ_PASSWORD', 'guest'),
                   'vhost'    => Env::string('RABBITMQ_VHOST', '/'),
                   'secret'   => Env::string('QUEUE_SECRET') ?? throw new \RuntimeException('QUEUE_SECRET is required'),
               ]),
    'array' => new ArrayQueue(),
    default => new SyncQueue(),
};
$app->setQueue($queue);

#Змінні оточення RabbitMQ

Використовуються, коли QUEUE_DRIVER=amqp. Потребують composer require php-amqplib/php-amqplib "^3.0".

QUEUE_DRIVER=amqp
RABBITMQ_HOST=rabbitmq.internal
RABBITMQ_USER=myapp
RABBITMQ_PASSWORD=secret
RABBITMQ_VHOST=/myapp

#Redis

Використовується кешем, чергою та драйверами сесій на базі Redis.

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=secret
REDIS_DB=0

#Логування

LOG_CHANNEL=file
LOG_LEVEL=warning
LOG_PATH=storage/logs/app.log
LOG_FORMAT=json

$formatter = Env::string('LOG_FORMAT', 'line') === 'json'
    ? new JsonFormatter()
    : new LineFormatter();

$handler = match (Env::string('LOG_CHANNEL', 'stdout')) {
    'file'   => new FileHandler(Env::string('LOG_PATH', 'storage/logs/app.log'),
                                Env::string('LOG_LEVEL', 'debug'), $formatter),
    'null'   => new NullHandler(),
    default  => new StdoutHandler(Env::string('LOG_LEVEL', 'debug'), $formatter),
};
$logger = new Logger([$handler]);
$app->instance(Logger::class, $logger);

#Шаблони

VIEWS_PATH=resources/views
VIEWS_EXTENSION=php
ASSET_BASE=/static

$app->views(
    path:      Env::string('VIEWS_PATH', __DIR__ . '/../views'),
    extension: Env::string('VIEWS_EXTENSION', 'php'),
    assetBase: Env::string('ASSET_BASE', '/assets'),
);

#Панель налагодження

Увімкнена лише коли APP_DEBUG=true. Ніколи не вмикайте у продакшені.

$app->debug([
    'enabled'           => Env::bool('APP_DEBUG', false),
    'toolbar'           => Env::bool('DEBUG_TOOLBAR', true),
    'position'          => Env::string('DEBUG_TOOLBAR_POSITION', 'bottom-right'),
    'track_php_errors'  => Env::bool('DEBUG_TRACK_PHP_ERRORS', true),
    'render_exceptions' => Env::bool('DEBUG_RENDER_EXCEPTIONS', true),
]);

#JWT

JWT_SECRET=your-256-bit-secret
JWT_ALGORITHM=HS256
JWT_TTL=3600

$jwt = new Jwt(
    secret:    Env::string('JWT_SECRET') ?? throw new \RuntimeException('JWT_SECRET is required'),
    algorithm: JwtAlgorithm::from(Env::string('JWT_ALGORITHM', 'HS256')),
    ttl:       Env::int('JWT_TTL', 3600),
);
$app->use(new JwtMiddleware($jwt));

#CORS

CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
CORS_ALLOW_CREDENTIALS=true
CORS_MAX_AGE=86400

$app->use(new CorsMiddleware(
    allowedOrigins:    explode(',', Env::string('CORS_ALLOWED_ORIGINS', '*')),
    allowedMethods:    explode(',', Env::string('CORS_ALLOWED_METHODS', 'GET,POST,PUT,PATCH,DELETE,OPTIONS')),
    allowedHeaders:    explode(',', Env::string('CORS_ALLOWED_HEADERS', 'Content-Type,Authorization')),
    allowCredentials:  Env::bool('CORS_ALLOW_CREDENTIALS', false),
    maxAge:            Env::int('CORS_MAX_AGE', 0),
));

#Сховище / Файлова система

STORAGE_DRIVER=local
STORAGE_PATH=storage/app
STORAGE_URL=https://cdn.example.com/files

$storage = new Storage();
$storage->addDisk('local', new LocalFilesystem(
    root:      Env::string('STORAGE_PATH', __DIR__ . '/../storage/app'),
    publicUrl: Env::string('STORAGE_URL'),
));
$storage->setDefault('local');
Storage::setInstance($storage);
$app->instance(Storage::class, $storage);

#Обмеження частоти запитів

$app->use(new RateLimitMiddleware(
    maxRequests: Env::int('RATE_LIMIT_MAX', 60),
    windowSecs:  Env::int('RATE_LIMIT_WINDOW', 60),
));

#Заголовки безпеки

SecurityHeadersMiddleware постачається з безпечними значеннями за замовчуванням. Змінні оточення не потрібні — налаштовуйте його напряму в коді:

$app->use(new SecurityHeadersMiddleware(
    contentSecurityPolicy: "default-src 'self'",
    frameOptions:          'DENY',
    xssProtection:         '1; mode=block',
    noSniff:               true,
    referrerPolicy:        'strict-origin-when-cross-origin',
    hsts:                  'max-age=31536000; includeSubDomains',
));

#CSRF

$app->use(new CsrfMiddleware(
    session:     $session,
    tokenName:   Env::string('CSRF_TOKEN_NAME', '_token'),
    headerName:  Env::string('CSRF_HEADER_NAME', 'X-CSRF-Token'),
));

#HTTP-клієнт

Налаштуйте значення за замовчуванням для вихідних запитів:

$client = HttpClient::new()
    ->timeout(Env::int('HTTP_CLIENT_TIMEOUT', 30))
    ->withHeaders([
        'User-Agent' => Env::string('APP_NAME', 'Lift App') . '/1.0',
    ]);
$app->instance(HttpClient::class, $client);

#Повний приклад .env

# Застосунок
APP_NAME="My Lift App"
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:ZmRzZmRzZmRzZmRzZmRzZmRzZmRzZmRzZmRzZmQ=
APP_URL=https://myapp.example.com

# База даних
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=myapp_user
DB_PASSWORD=secret

# Сесія
SESSION_DRIVER=file
SESSION_PATH=storage/sessions
SESSION_LIFETIME=7200

# Кеш
CACHE_DRIVER=redis
CACHE_PREFIX=myapp_

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# Черга
QUEUE_DRIVER=redis

# Логування
LOG_CHANNEL=file
LOG_LEVEL=warning
LOG_PATH=storage/logs/app.log

# JWT
JWT_SECRET=your-very-long-random-secret-key-here
JWT_TTL=3600

# CORS
CORS_ALLOWED_ORIGINS=https://myapp.example.com