[ Laravel 5.7 文档 ] 快速入门 —— 安装配置

服务器要求

Laravel 框架对 PHP 版本和扩展有一定要求，不过这些要求 Laravel Homestead 都已经满足了，不过如果你没有使用 Homestead 的话（那真是一件很遗憾的事情），有必要了解下这些以便确认自己的环境满足要求：

• PHP >= 7.1.3
• PHP OpenSSL 扩展
• PHP PDO 扩展
• PHP Mbstring 扩展
• PHP Tokenizer 扩展
• PHP XML 扩展
• PHP Ctype 扩展
• PHP JSON 扩展

满足以上需求之后，就可以开始安装 Laravel 了。

安装 Laravel

Laravel 使用 Composer 管理依赖，所以，安装之前确保已经在机器上安装了 Composer（如果尚未安装的话参考 这份文档 去安装吧）。

通过 Laravel 安装器

首先，通过 Composer 安装 Laravel 安装器：

composer global require "laravel/installer"

确保 $HOME/.composer/vendor/bin 在系统路径中（Mac中对应路径是 ~/.composer/vendor/bin ，Windows对应路径是 ~/AppData/Roaming/Composer/vendor/bin ，其中 ~ 表示当前用户家目录），否则不能在命令行任意路径下调用 laravel 命令。

安装完成后，通过简单的 laravel new 命令即可在当前目录下创建一个新的 Laravel 应用，例如， laravel new blog 将会创建一个名为 blog 的新应用，且包含所有 Laravel 依赖。该安装方法比通过 Composer 安装要快很多：

laravel new blog

如果之前已经安装过旧版本的 Laravel 安装器，需要更新后才能安装最新的 Laravel 5.7 框架应用：

composer global update

通过 Composer Create-Project

你还可以在终端中通过 Composer 的 create-project 命令来安装 Laravel 应用：

composer create-project --prefer-dist laravel/laravel blog

如果要下载安装 Laravel 其他版本应用，比如 5.6 版本，可以使用这个命令：

composer create-project --prefer-dist laravel/laravel blog 5.6.*。

本地开发服务器

如果你在本地安装了 PHP，并且想要使用 PHP 内置的开发环境服务器为应用提供服务，可以使用 Artisan 命令 serve ：

php artisan serve

该命令将会在本地启动开发环境服务器，这样在浏览器中通过 http://localhost:8000 即可访问应用：

当然，更强大的本地开发环境选择还是 Homestead 和 Valet。

配置 Laravel

初始化配置

公共目录

安装完 Laravel 后，需要将 Web 服务器的 document/web 根目录指向 Laravel 应用的 public 目录，该目录下的 index.php 文件作为前端控制器（单一入口），所有 HTTP 请求都会通过该文件进入应用。

配置文件

Laravel 框架的所有配置文件都存放在 config 目录下，所有的配置项都有注释，所以你可以轻松遍览这些配置文件以便熟悉所有配置项。

目录权限

安装完 Laravel 后，需要配置一些目录的读写权限： storage 和 bootstrap/cache 目录对 Web 服务器指定的用户而言应该是可写的，否则 Laravel 应用将不能正常运行。如果你使用 Homestead 虚拟机做为开发环境，这些权限已经设置好了。

应用key

接下来要做的事情就是将应用的 key（APP_KEY）设置为一个随机字符串，如果你是通过 Composer 或者 Laravel 安装器安装的话，该 key 的值已经通过 php artisan key:generate 命令生成好了。

通常，该字符串应该是 32 位长，通过 .env 文件中的 APP_KEY 进行配置，如果你还没有将 .env.example 文件重命名为 .env ，现在立即这样做。 如果应用 key 没有被设置，用户 Session 和其它加密数据将会有安全隐患!

更多配置

Laravel 几乎不再需要其它任何配置就可以正常使用了，不过，你最好再看看 config/app.php 文件，其中包含了一些基于应用可能需要进行改变的配置，比如 timezone 和 locale （分别用于配置时区和本地化）。

你可能还想要配置 Laravel 的一些其它组件，比如缓存、数据库、Session 等，关于这些我们将会在后续文档一一探讨。

Web 服务器配置

关于虚拟主机的配置（映射域名到 Laravel 应用目录）略过，如果了解细节可参考这篇教程，当然也可以留待下一篇讲 Homestead 和 Valet 再去了解。本文只探讨如何美化 URL 让其更具有可读性。

Apache

框架中自带的 public/.htaccess 文件支持隐藏 URL 中的 index.php ，如过你的 Laravel 应用使用 Apache 作为服务器，需要先确保 Apache 启用了 mod_rewrite 模块以支持 .htaccess 解析。

如果 Laravel 自带的 .htaccess 文件不起作用，试试将其中内容做如下替换：

Options +FollowSymLinks
RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

Nginx

如果你使用的是 Nginx，使用如下站点配置指令就可以支持 URL 美化：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

当然，使用 Homestead 或 Valet 的话，以上配置已经为你配置好，无需额外操作。

环境配置

基于应用运行的环境不同设置不同的配置值能够给我们开发带来极大的方便，比如，我们通常在本地和线上环境配置不同的缓存驱动，这一功能在 Laravel 中很容易实现。

Laravel 使用 PHP 扩展库 DotEnv 来实现这一功能，在新安装的 Laravel 中，根目录下有一个 .env.example 文件，如果 Laravel 是通过 Composer 安装的，那么该文件已经被重命名为 .env ，否则的话你要自己手动重命名该文件。

不要试图将 .env 文件提交到版本控制系统（如Git或Svn）中，一方面，开发环境和线上环境配置值不一样，提交没有意义，更重要的是， .env 包含了很多应用敏感信息，如数据库用户名及密码等，如果不慎将代码提交到 Github 公开仓库，后果将不堪设想！

如果你是在一个团队中进行开发，则需要将 .env.example 文件随你的应用代码一起提交到源码控制中：将一些配置值以占位符的方式放置在 .env.example 文件中，这样其他开发者就会很清楚运行你的应用需要配置哪些环境变量。

还可以创建一个 .env.testing 文件，该文件会在运行 PHPUnit 测试或执行带有 --env=testing 选项的 Artisan 命令时覆盖从 .env 文件读取的值。

注： .env 文件中的所有变量都可以被外部环境变量覆盖，例如服务器级别或系统级别的环境变量。

环境变量类型

.env 文件中所有变量都会被解析为字符串，因此创建了一些保留值以便从 env() 函数返回更广泛的类型：

如果你需要定义一个包含空格的环境变量值，可以通过将字符串放到双引号中来实现：

APP_NAME="My Application"

获取环境变量配置值

应用每次接受请求时， .env 中列出的所有配置及其对应值都会被载入到 PHP 超全局变量 $_ENV 中，然后你就可以在应用中通过辅助函数 env 来获取这些配置值。实际上，如果你去查看 Laravel 的配置文件，就会发现很多地方已经在使用这个辅助函数了：

'debug' => env('APP_DEBUG', false),

传递到 env 函数的第二个参数是默认值，如果环境变量没有被配置将会使用该默认值。

判断当前应用环境

当前应用环境由 .env 文件中的 APP_ENV 变量决定，你可以通过 App 门面上的 environment 方法来访问其值：

$environment = App::environment();

你也可以向 environment 方法传递参数来判断当前环境是否匹配给定值，如果需要的话你甚至可以传递多个值。如果当前环境与给定值匹配，该方法返回 true ：

if (App::environment('local')) {
    // The environment is local
}

if (App::environment('local', 'staging')) {
    // The environment is either local OR staging...
}

注：当前应用环境判断可以被服务器级别环境变量 APP_ENV 覆盖。当你需要在不同环境配置间共享同一应用时很有用，你可以在服务器配置中设置一个给定主机来匹配给定环境。

访问配置值

你可以使用全局辅助函数 config 在应用代码的任意位置访问配置值，配置值以 文件名+“.”+配置项 的方式进行访问，当配置项没有被配置的时候返回默认值：

$value = config('app.timezone');

如果要在运行时设置配置值，传递数组参数到 config 方法即可：

config(['app.timezone' => 'Asia/Shanghai']);

缓存配置文件

为了给应用加速，你可以使用 Artisan 命令 config:cache 将所有配置文件的配置缓存到单个文件里，这将会将所有配置选项合并到单个文件从而被框架快速加载。

应用每次上线，都要运行一次 php artisan config:cache ，但是在本地开发时，没必要经常运行该命令，因为配置值经常会改变。

注：如果在部署过程中执行 config:cache 命令，需要确保只在配置文件中调用了 env 方法。一旦配置文件被缓存后， .env 文件将不能被加载，所有对 env 函数的调用都会返回 null 。

维护模式

当你的应用处于维护模式时，所有对应用的请求都应该返回同一个自定义视图。这一功能在对应用进行升级或者维护时，使得“关闭”站点变得轻而易举。对维护模式的判断代码位于应用默认的中间件栈中，如果应用处于维护模式，访问应用时状态码为 503 的 MaintenanceModeException 将会被抛出。

要开启维护模式，关闭站点，只需执行 Artisan 命令 down 即可：

php artisan down

还可以提供 message 和 retry 选项给 down 命令。 message 的值用于显示或记录自定义消息，而 retry 的值用于设置 HTTP 请求头的 Retry-After ：

php artisan down --message="Upgrading Database" --retry=60

即使在维护模式下，也可以通过 allow 选项指定 IP 地址或网络来访问应用：

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

要关闭维护模式，开启站点，对应的 Artisan 命令是 up ：

php artisan up

注：你可以通过定义自己的模板来定制默认的维护模式模板，自定义模板视图位于 resources/views/errors/503.blade.php 。

维护模式 & 队列

当你的站点处于维护模式中时，所有的队列任务都不会执行；当应用退出维护模式这些任务才会被继续正常处理。

维护模式的替代方案

由于维护模式命令的执行需要几秒时间，你可以考虑使用 Envoyer 实现零秒下线作为替代方案。