配置文件

StartMVC 框架的配置系统提供了一种简单、灵活的方式来管理应用程序的各种配置。配置系统支持多环境配置、点语法访问、自动按需加载等特性，使开发者能够轻松管理和访问应用配置。

配置文件

配置文件位于项目根目录的 config 目录下，框架自带的文件有：

• common.php —— 系统基础配置（调试、时区、默认模块、Session / Cookie / CSRF 安全配置等）
• database.php —— 数据库连接配置
• cache.php —— 缓存驱动配置
• log.php —— 日志配置
• route.php —— 路由配置
• middleware.php —— 中间件别名与全局中间件配置
• pagination.php —— 分页配置
• view.php —— 视图 / 模板配置

除自带文件外，还可以在 config 目录下新增任意配置文件，用 config('文件名.键名') 访问，访问时自动按需加载。

配置加载机制

配置系统采用自动按需加载机制：

• common.php 在首次使用配置系统时自动加载
• 其他配置文件在首次被访问时自动加载（无需手动预加载）
• 所有加载过的配置都会被缓存，避免重复加载

另外，以下两个文件会在 common.php 之上叠加（存在才加载）：

• {ENV}.php —— 按环境变量 ENV 命名，用于区分开发 / 测试 / 生产环境
• local.php —— 开发者个人配置，通常不纳入版本控制

叠加优先级：local.php > {ENV}.php > common.php。同名键若都是数组会做合并，否则直接覆盖。

使用方法

助手函数 config()

框架提供了 config() 助手函数，是访问配置的最简单方式：

// 获取所有配置
$allConfig = config();

// 获取特定配置项（自动加载对应配置文件）
$debug = config('debug');
$dbHost = config('database.connections.mysql.host');

// 读取配置项，并在不存在时给出默认值（第二个参数是默认值，不是"设置"）
$host = config('database.connections.mysql.host', 'localhost');

// 批量设置配置（传数组）
config([
 'site.title' => '我的网站',
 'site.description' => '网站描述'
]);

// 显式加载某个配置文件（可选，向后兼容）
$dbConfig = config('@database');

config() 函数的实现具有以下特点：

1. 当不带参数调用时，返回所有配置（Config::get()）
2. 当参数以 @ 开头时，会调用 Config::load() 方法按需加载指定的配置文件
3. 当参数是数组时，会循环设置多个配置项（Config::set()）
4. 当有两个参数时，第二个参数是默认值，即读取配置项、不存在时返回该默认值
5. 其他情况下，获取指定的配置项

直接使用 Config 类

也可以直接使用 Config 类：

use startmvc\core\Config;

// 获取配置
$host = Config::get('database.connections.mysql.host');

// 提供默认值的用法 - 当配置项不存在时返回默认值
$host = Config::get('database.connections.mysql.host', 'localhost');

// 设置配置
Config::set('debug', false);

// 检查配置是否存在
if (Config::has('cache.redis.port')) {
 // 使用配置
}

// 加载特定配置文件
$redisConfig = Config::load('cache');

// 获取配置分组
$cacheSettings = Config::group('cache');

点语法

配置系统支持使用点语法访问嵌套配置，第一段是配置文件名，之后逐级对应数组的键：

// 访问数据库配置
$driver = config('database.driver'); // 返回 'mysql'
$mysqlHost = config('database.connections.mysql.host'); // 返回 'localhost'
$mysqlPort = config('database.connections.mysql.port'); // 返回 3306

示例配置文件

// config/common.php
return [
 'debug' => true, // Debug模式，开发过程中开启，生产环境中请关闭
 'trace' => true, // 是否附加调试追踪面板（仅对 HTML 页面生效），生产环境中请关闭
 'route_cache' => true, // 路由编译缓存，以 config/route.php 修改时间 + 框架版本号为失效键
 'timezone' => 'Asia/Shanghai', // 系统时区
 'url_suffix' => '.html', // URL后缀
 'default_module' => 'home', // 默认模块
 'default_controller' => 'Index',// 默认控制器
 'default_action' => 'index', // 默认方法
 'urlrewrite' => true, // 是否Url重写，隐藏index.php，需要服务器支持和对应的规则
 'session_prefix' => '', // Session前缀
 'cookie_prefix' => '', // Cookie前缀
 'locale' => 'zh_cn', // 指定默认语言，小写
 'db_auto_connect' => true,// 是否开启数据库自动连接
 'theme' => '', // 指定模板子目录，方便多风格使用，为空时模板文件在view下
 // 可信代理IP列表：仅当 REMOTE_ADDR 命中此列表时才信任 X-Forwarded-For
 'trusted_proxies' => [],
];

// config/database.php（仅节选 mysql 连接）
return [
 'driver' => 'mysql',
 'connections' => [
 'mysql' => [
 'host' => 'localhost',
 'database' => 'startmvc',
 'username' => 'root',
 'password' => '',
 'charset' => 'utf8',
 'port' => 3306,
 'prefix' => 'sm_',
 'cachetime' => 3600,
 'debug' => false, // 报错时输出详细SQL，生产环境必须false
 'options' => [], // 连接选项（如SSL证书等，可选）
 ],
 ],
];

// config/cache.php
return [
 'drive' => 'file', //默认驱动支持 file,redis,memcached 缓存
 'file' => [
 'cacheDir' => 'cache/',
 'cacheTime' => 3600
 ],
 'redis' => [
 'host' => '127.0.0.1',
 'port' => 6379,
 'password' => '',
 'database' => 0,
 'cacheTime' => 3600
 ],
 'memcached' => [
 'host' => '127.0.0.1',
 'port' => 11211,
 'cacheTime' => 3600
 ],
];

// config/log.php
return [
 'enabled' => true, // 日志总开关，false 时所有写入直接丢弃
 'path' => null, // 日志目录（绝对路径），留空则使用 runtime/logs
 'level' => 'debug', // 最低记录级别，低于该级别的日志被静默丢弃
 'split' => true, // 是否按级别分文件：true 得到 2026-09-12_error.log，false 得到 2026-09-12.log
];

日志配置

框架内所有日志（含 Exception 异常处理器的错误记录）都统一经由 startmvc\core\Logger 写入，不再各自拼路径、各写各的文件。日志相关的四项配置见上方 config/log.php。

常用写法：

use startmvc\core\Logger;

$logger = new Logger();
$logger->info('用户登录', ['id' => 42]); // [2026-09-12 21:30:00] INFO: 用户登录
$logger->warning('库存不足');
$logger->error('支付回调处理失败');

要点：

• 日志级别按严重度递增为 debug < info < notice < warning < error < critical < alert < emergency，八个级别都有对应的快捷方法（debug() / info() / ... / emergency()）。传入未定义的级别会抛出 InvalidArgumentException。
• 写入采用追加方式并加锁，写入失败只返回 false、绝不抛异常，避免日志问题影响业务（尤其是异常处理器里的日志记录）。
• 日志目录不可写时会自动退化到系统临时目录（sys_get_temp_dir()/startmvc-logs），仍不可用则静默丢弃。
• 生产环境建议把 level 调为 warning，避免 debug 日志堆积。

使用示例

// 获取系统调试模式
$debug = config('debug');

// 获取数据库连接信息（自动加载 database.php）
$db = config('database');
$dbDriver = config('database.driver');
$dbHost = config('database.connections.mysql.host');
$dbName = config('database.connections.mysql.database');

// 批量修改配置
config([
 'debug' => false,
 'trace' => false,
]);

// 直接用 Config 类设置单个配置项
Config::set('debug', false);

// 检查配置是否存在
if (Config::has('database.connections.mysql.port')) {
 $port = config('database.connections.mysql.port');
} else {
 $port = 3306;
}

// 获取缓存配置（自动加载 cache.php）
$cacheDriver = config('cache.drive');
$redisHost = config('cache.redis.host');