配置 · ThinkPHP5.1完全开发手册

## 配置基础 `ThinkPHP`遵循惯例重于配置的原则，系统会按照下面的顺序来加载配置文件（配置的优先顺序从右到左）。 >[info]#### 惯例配置->应用配置->模块配置->动态配置 * **惯例配置**：核心框架内置的配置文件，无需更改。 * **应用配置**：每个应用的全局配置文件（框架安装后会生成初始的应用配置文件），有部分配置参数仅能在应用配置文件中设置。 * **模块配置**：每个模块的配置文件（相同的配置参数会覆盖应用配置），有部分配置参数模块配置是无效的，因为已经使用过。 * **动态配置**：主要是指在控制器或者行为中进行（动态）更改配置，该配置方式只在当次请求有效，因为不会保存到配置文件中。 >[info] 和5.0最大的区别是，5.1版本的配置参数全部是二级配置，当没有指定一级配置名的时候，默认就是以`app`作为一级配置，一级配置名称通常来说就是所在的配置文件名。 ## 配置文件和目录为更好的应对模块化的开发要求，`5.1`的应用配置主要包括**应用配置**目录和**模块配置**目录，结构如下： ~~~ ├─config（应用配置目录） │ ├─app.php 应用配置 │ ├─cache.php 缓存配置 │ ├─cookie.php Cookie配置 │ ├─database.php 数据库配置 │ ├─log.php 日志配置 │ ├─session.php Session配置 │ ├─template.php 模板引擎配置 │ ├─trace.php Trace配置 │ └─ ... 更多配置文件 │ ├─route（路由目录） │ ├─route.php 路由定义文件 │ └─ ... 更多路由定义文件 │ ├─application （应用目录） │ └─module （模块目录） │ └─config（模块配置目录） │ ├─app.php 应用配置 │ ├─cache.php 缓存配置 │ ├─cookie.php Cookie配置 │ ├─database.php 数据库配置 │ ├─log.php 日志配置 │ ├─session.php Session配置 │ ├─template.php 模板引擎配置 │ ├─trace.php Trace配置 │ └─ ... 更多配置文件 │ ~~~ >[danger] 一定注意了，5.1没有`config.php`配置文件，默认配置都在`app.php`配置文件，并且配置参数**区分大小写** 上面的目录结构是只是列出系统内置的配置文件，你还可以增加其他的自定义配置文件，配置文件的名称就是一级配置名。 >[danger] 因为架构设计要求，`5.1`的路由配置文件（确切来说应该是路由定义文件）独立于配置文件（更多会在路由章节中讲述）。应用和模块的配置目录对应关系为：配置|目录 ---|--- 应用配置目录|config 模块配置目录|application/module/config 如果你需要统一管理所有的配置文件，那么可以把模块目录下面的`config`目录移动到应用配置目录下面改为模块子目录的方式，调整后的配置目录的结构如下： ~~~ ├─application（应用目录） ├─config（配置目录） │ ├─module （模块配置目录） │ │ ├─database.php 数据库配置 │ │ ├─cache 缓存配置 │ │ └─ ... │ │ │ ├─app.php 应用配置 │ ├─cache.php 缓存配置 │ ├─cookie.php Cookie配置 │ ├─database.php 数据库配置 │ ├─log.php 日志配置 │ ├─session.php Session配置 │ ├─template.php 模板引擎配置 │ └─trace.php Trace配置 │ ├─route（路由配置目录） │ ├─route.php 路由定义文件 │ └─ ... 更多路由定义文件 ~~~ >[danger] 一旦模块目录下面存在`config`目录，则应用配置目录下的模块配置则无效，也不会对两个目录的配置进行合并。这样一来，配置目录对应关系变成：配置|目录 ---|--- 应用配置目录|config 模块配置目录|config/module **每个配置文件中都有详细的配置参数说明，可以仔细查看。** ## 配置定义可以直接在相应的应用或模块配置文件中修改或者增加配置参数，如果你要增加额外的配置文件，直接放入应用或模块配置目录即可（文件名小写）。 >[danger] 除了一级配置外，配置参数名严格区分大小写，建议是使用小写定义配置参数的规范。另外涉及到配置参数的定义有效性问题，下列配置参数在模块配置中定义（包括动态配置）无效，而**必须在应用配置中设置**：配置参数|描述 ---|--- app_debug|应用调试模式（支持环境变量配置） app_trace|应用trace（支持环境变量配置） class_suffix|类后缀 default_filter|默认过滤机制 root_namespace|根命名空间 pathinfo_depr|PATH_INFO分隔符 url_route_must|路由强制模式 auto_bind_module|自动绑定模块 default_lang|默认语言 lang_switch_on|多语言切换由于架构设计原因，下面的配置只能在环境变量中修改。配置参数|描述 ---|--- app_namespace|应用命名空间 config_ext|配置文件后缀 ### 其它配置格式支持默认的配置文件都是PHP数组方式，如果你需要使用其它格式的配置文件，你可以通过改变`CONFIG_EXT`**环境变量**的方式来更改配置类型。在应用根目录的`.env`或者系统环境变量中设置 ~~~ CONFIG_EXT=".ini" ~~~ 支持的配置类型包括` .ini`、`.xml`、`.json` 、`.yaml`和 `.php` 在内的格式支持，配置后应用配置及模块配置必须统一使用相同的配置类型。 ### 二级配置配置参数的值同样支持数组，下面是示例： ~~~ return [ 'user' => [ 'type' => 1, 'name' => 'thinkphp', ], 'db' => [ 'type' => 'mysql', 'user' => 'root', 'password' => '', ], ]; ~~~ ### 环境变量定义可以在应用的根目录下定义一个特殊的`.env`环境变量文件，用于在开发过程中模拟环境变量配置（该文件建议在服务器部署的时候忽略），`.env`文件中的配置参数定义格式采用`ini`方式，例如： ~~~ APP_DEBUG = true APP_TRACE = true ~~~ >[danger] 如果你的部署环境单独配置了环境变量（环境变量的前缀使用`PHP_`），那么请删除`.env`配置文件，避免冲突。环境变量配置的参数会全部转换为大写，值为 `null`，`no` 和 `false` 等效于 `""`，值为 `yes` 和 `true` 等效于 `"1"`。注意，环境变量不支持数组参数，如果需要使用数组参数可以，使用下划线分割定义配置参数名： ~~~ DATABASE_USERNAME = root DATABASE_PASSWORD = 123456 ~~~ 获取环境变量的值使用下面的方式： ~~~ Env::get('database_username'); Env::get('database_password'); ~~~ 如果使用 ~~~ [DATABASE] USERNAME = root PASSWORD = 123456 ~~~ 获取环境变量的值可以使用下面的方式获取： ~~~ Env::get('database.username'); Env::get('database.password'); ~~~ 要使用`Env`类，必须先引入`think\facade\Env`或者`\Env`。 >[danger] 环境变量的获取不区分大小写可以支持默认值，例如： ~~~ // 获取环境变量如果不存在则使用默认值root Env::get('database.username','root'); ~~~ 可以直接在配置文件中使用环境变量进行本地环境和服务器的自动配置，例如： ~~~ return [ 'hostname' => Env::get('hostname','127.0.0.1'), ]; ~~~ >[danger] 环境变量中设置的`APP_DEBUG`和`APP_TRACE`参数会自动生效（优先于应用的配置文件），其它参数则必须通过`Env::get`方法才能读取。 ## 配置获取要使用`Config`类，首先需要在你的类文件中引入 ~~~ use think\facade\Config; ~~~ 或者（因为系统做了类库别名，其实就是调用`think\facade\Config`） ~~~ use Config; ~~~ 然后就可以使用下面的方法读取某个配置参数的值： ~~~ echo Config::get('配置参数1'); ~~~ 如果你需要读取某个一级配置的所有配置参数，可以使用 ~~~ Config::pull('app'); ~~~ 或者使用 ~~~ Config::get('app.'); ~~~ 读取所有的配置参数： ~~~ dump(Config::get()); ~~~ 判断是否存在某个设置参数： ~~~ Config::has('配置参数2'); ~~~ ## 助手函数系统定义了一个助手函数`config`，以上可以简化为： ~~~ echo config('配置参数1'); ~~~ `5.1`的配置参数全部采用二级配置的方式（默认一级配置为app），所以当你使用`config('name')`的时候其实相当于使用： ~~~ config('app.name') ~~~ 支持获取多级配置参数值，直接使用（必须从一级开始写） ~~~ config('app.name1.name2') ~~~ 获取某个一级配置的所有参数可以使用 ~~~ config('app.'); ~~~ 读取所有的配置参数： ~~~ dump(config()); ~~~ 或者你需要判断是否存在某个设置参数： ~~~ config('?配置参数2'); ~~~ ## 动态设置（慎用） >[danger] `V5.1.18+`版本以上，不再建议使用动态配置，由于容器的特性，可能不会生效。在控制器或者行为里面可以使用`set`方法或者助手函数动态设置参数（不过需要注意的是，动态设置生效的前提是该参数尚未被使用），格式： ~~~ Config::set('配置文件名.配置参数','配置值'); // 或者使用助手函数 config('配置文件名.配置参数','配置值'); ~~~ 动态设置的参数，最多支持二级，例如： ~~~ Config::set('app_trace', true); // 没有指定配置文件名的话等效于下面的方式 Config::set('app.app_trace', true); // 助手函数的方式 config('app_trace', true); ~~~ 也可以传入数组批量设置，并在第二个参数传入一级配置名，例如： ~~~ Config::set([ 'app_trace'=>true, 'show_error_msg'=>true ], 'app'); // 或者使用助手函数 config([ 'app_trace'=>true, 'show_error_msg'=>true ],'app'); ~~~ ## 系统配置文件下面系统自带的配置文件列表及其作用（配置文件可能同时存在应用配置文件和模块配置文件两个同名文件）：配置文件名|描述 ---|--- app.php|应用配置 cache.php|缓存配置 cookie.php|Cookie配置 database.php|数据库配置 log.php|日志配置 session.php|Session配置 template.php|模板引擎配置 trace.php|页面Trace配置 paginate.php|分页配置具体的配置参数可以直接查看应用`config`目录下面的相关文件内容。 ## 使用`Yaconf`定义（`V5.1.22+`）从`V5.1.22+`版本开始（并且要求`PHP7+`），可以支持使用`Yaconf`统一定义配置，但不支持动态设置。 `V5.1.23+`版本开始，可以使用`setYaconf`方法指定`Yaconf`使用的独立配置文件，例如： ~~~ // 建议在应用的公共函数文件中进行设置 think\facade\Config::setYaconf('thinkphp'); ~~~ 设置后，你只需要在`thinkphp.ini`一个文件进行项目的配置，而无需分开多个文件，避免和其它项目冲突。同时，你还可以在配置文件中，使用`yaconf`助手函数（用法类似`env`函数） ~~~ return [ 'config_name' => yaconf('config_name', 'default_value'), ]; ~~~ >[danger] `setYaconf`方法的设置对`yaconf`助手函数依然有效 > 关于`Yaconf`的安装和配置用法可以[参考这里](http://www.laruence.com/2015/06/12/3051.html)。