本文介绍如何利用 Laravel 框架，将 phpDocumentor 生成的静态文档安全地提供给授权用户访问。通过配置 CI/CD 流程，自动生成文档并将其存储在 Laravel 的存储目录中，然后通过自定义路由和中间件，实现对文档访问的权限控制。本文提供详细步骤和示例代码，帮助开发者轻松集成 phpDocumentor 文档到 Laravel 项目中，并确保文档的安全性。
集成 phpDocumentor 文档到 Laravel 项目
在 Laravel 项目中集成 phpDocumentor 文档，并限制访问权限，需要几个关键步骤。 首先，我们需要在 CI/CD 流程中集成 phpDocumentor 的生成过程，然后配置 Laravel 的文件系统，并创建一个路由来提供文档。最后，使用中间件来保护路由，确保只有授权用户才能访问文档。
步骤 1: CI/CD 中生成 phpDocumentor 文档
在你的 CI/CD 脚本中添加 phpDocumentor 的生成命令。首先，确保服务器上安装了 phpDocumentor。然后，使用以下命令生成文档：
phpDocumentor -d . -t storage/docs/
此命令指示 phpDocumentor 从当前目录（-d .）读取代码，并将生成的文档输出到 storage/docs/ 目录（-t storage/docs/）。
立即学习“PHP免费学习笔记（深入）”；
注意事项:
- storage 目录通常会被 .gitignore 文件忽略。如果计划在非生产服务器上生成 phpDoc，请确保将 storage/docs/ 目录推送到生产服务器。
- 根据你的项目结构和需求，调整 -d 和 -t 参数。
步骤 2: 配置 Laravel 文件系统
接下来，需要在 config/filesystem.php 文件中添加一个新的磁盘配置，用于访问生成的文档。
'disks' => [
// 其他磁盘配置...
'local-docs' => [
'driver' => 'local',
'root' => storage_path('docs'),
],
],此配置定义了一个名为 local-docs 的磁盘，它使用本地驱动，并将根目录设置为 storage/docs/。
步骤 3: 创建路由并应用中间件
在 routes/web.php 文件中，创建一个路由来提供文档。使用 Storage facade 来读取文档，并设置正确的 content-type 头部。
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Storage;
use GuzzleHttp\Psr7\MimeType;
Route::get('/docs/{url?}', function ($url = null) {
if (is_null($url)) {
$url = 'index.html'; // 默认显示 index.html
}
if (!Storage::disk('local-docs')->exists($url)) {
abort(404); // 如果文件不存在，返回 404 错误
}
$resp = response(Storage::disk('local-docs')->get($url));
$resp->header('Content-Type', MimeType::fromFilename($url));
return $resp;
})->where('url', '(.*)')->middleware('auth');这个路由处理对 /docs 路径的请求。它接受一个可选的 url 参数，用于指定要访问的文档文件。where('url', '(.*)') 约束确保路由可以匹配任何 URL。 middleware('auth') 应用了 auth 中间件，确保只有经过身份验证的用户才能访问该路由。
注意事项:
- 确保没有其他路由使用 docs 前缀，否则可能会导致路由冲突。
- 如果用户未登录，auth 中间件会将他们重定向到登录页面。你可以根据需要自定义此行为。
- 为了更友好的用户体验，在路由中添加了对默认显示 index.html 和文件不存在时返回 404 错误的处理。
总结
通过以上步骤，你可以将 phpDocumentor 生成的文档集成到 Laravel 项目中，并使用 Laravel 的身份验证机制来保护文档的访问。 这种方法可以确保只有授权用户才能访问文档，并允许通过 CI/CD 流程自动更新文档。
