使用 Laravel 安全地提供 phpDocumentor 生成的文档

本文介绍了如何将 phpDocumentor 生成的文档集成到 Laravel 项目中，并仅向授权用户提供访问权限。通过配置 CI/CD 流程、文件系统磁盘和路由，可以实现自动生成和安全访问文档的目标。

集成 phpDocumentor 文档到 Laravel 项目

本教程将指导你如何使用 Laravel 提供 phpDocumentor 生成的文档，并确保只有授权用户才能访问。这对于需要内部文档，并希望控制访问权限的项目非常有用。

步骤 1: 在 CI/CD 脚本中生成 phpDocumentor 文档

首先，需要在 CI/CD 脚本中集成 phpDocumentor 的生成过程。这可以确保每次部署时，文档都是最新的。

1. 安装 phpDocumentor:

   立即学习“PHP免费学习笔记（深入）”；

   在你的服务器上安装 phpDocumentor。可以使用 Composer 全局安装：

   composer global require phpdocumentor/phpdocumentor

2. 生成文档:

   使用以下命令生成文档。确保指定正确的源代码目录和目标目录。

   phpDocumentor -d . -t storage/docs/

   -d . 指定当前目录为源代码目录，-t storage/docs/ 指定生成的文档输出到 storage/docs/ 目录。

   重要提示: 如果 storage 目录被 .gitignore 忽略，确保在部署过程中将 storage/docs/ 目录包含进去，以便将其推送到生产服务器。

步骤 2: 配置 Laravel 文件系统

接下来，需要在 Laravel 的文件系统配置中添加一个新的磁盘，用于访问生成的文档。

1. 修改 config/filesystem.php:

   

   ECTouch移动商城系统

   ECTouch是上海商创网络科技有限公司推出的一套基于 PHP 和 MySQL 数据库构建的开源且易于使用的移动商城网店系统！应用于各种服务器平台的高效、快速和易于管理的网店解决方案，采用稳定的MVC框架开发，完美对接ecshop系统与模板堂众多模板，为中小企业提供最佳的移动电商解决方案。ECTouch程序源代码完全无加密。安装时只需将已集成的文件夹放进指定位置，通过浏览器访问一键安装，无需对已有

   下载

   在 config/filesystem.php 文件的 disks 数组中添加以下配置：

   'local-docs' => [
       'driver' => 'local',
       'root' => storage_path('docs'),
   ],

   这将创建一个名为 local-docs 的磁盘，它指向 storage/docs/ 目录。

步骤 3: 创建路由并应用中间件

现在，需要创建一个路由，用于提供文档，并应用 auth 中间件，以确保只有登录用户才能访问。

1. 修改 routes/web.php:

   在 routes/web.php 文件中添加以下路由：

   use Illuminate\Support\Facades\Route;
   use Illuminate\Support\Facades\Storage;
   use GuzzleHttp\Psr7\MimeType;
   
   Route::get('/docs/{url?}', function ($url = null) {
       if (Storage::disk('local-docs')->exists($url)) {
           $file = Storage::disk('local-docs')->get($url);
           $mimeType = MimeType::fromFilename($url);
           return response($file, 200)->header('Content-Type', $mimeType);
       } else {
           abort(404);
       }
   })->where('url', '(.*)')->middleware('auth');

   这个路由将拦截所有以 /docs/ 开头的请求，并尝试从 local-docs 磁盘中获取相应的文件。middleware('auth') 确保只有通过身份验证的用户才能访问此路由。where('url', '(.*)') 确保路由可以匹配包含子目录的 URL。

   注意: 确保没有其他路由使用了 docs 前缀，否则可能会导致冲突。

步骤 4: 确保正确的文件类型

为了确保浏览器能够正确地显示文档，需要设置正确的 Content-Type 头。上面的代码示例使用了 GuzzleHttp\Psr7\MimeType::fromFilename($url) 来根据文件名推断 MIME 类型。你需要确保安装了 guzzlehttp/psr7 包：

composer require guzzlehttp/psr7

总结

通过以上步骤，你已经成功地将 phpDocumentor 生成的文档集成到了 Laravel 项目中，并仅向授权用户提供访问权限。

注意事项:

• 定期更新 phpDocumentor，以获取最新的功能和安全修复。
• 确保 CI/CD 脚本能够正确地生成文档，并将文档部署到生产服务器。
• 定期检查路由和文件系统配置，以确保其正常工作。
• 根据需要调整路由和中间件，以满足项目的特定需求。

这个方法提供了一种安全且自动化的方式来管理和提供你的项目文档。