Laravel 中安全地提供 phpDocumentor 生成的文档-php教程-PHP中文网

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

花韻仙語

发布： 2025-10-16 11:55:01

原创

386人浏览过

laravel 中安全地提供 phpdocumentor 生成的文档

本文介绍如何利用 Laravel 框架，安全地提供 phpDocumentor 生成的文档，使其仅对授权用户可见。通过配置 CI/CD 流程，自动生成文档并存储在指定目录，然后通过自定义路由和中间件，实现文档的访问控制，确保只有登录用户才能访问项目文档。

使用 Laravel 安全地托管 phpDocumentor 文档

phpDocumentor 是一款强大的 PHP 文档生成工具，可以根据代码中的注释自动生成 API 文档。然而，在某些情况下，我们希望这些文档只能被授权用户访问，例如团队内部成员。本文将介绍如何利用 Laravel 框架，安全地托管 phpDocumentor 生成的文档，并实现访问控制。

步骤 1: 生成 phpDocumentor 文档

首先，需要在你的 Laravel 项目中安装 phpDocumentor。你可以通过 Composer 来完成：

composer require phpdocumentor/phpdocumentor

登录后复制

安装完成后，就可以使用 phpDocumentor 生成文档了。在你的 CI/CD 脚本中添加以下命令：

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

phpDocumentor -d . -t storage/docs/

登录后复制

这条命令会将当前目录（-d .）下的代码生成文档，并输出到 storage/docs/ 目录（-t storage/docs/）。

重要提示：

请确保 storage/docs/ 目录不会被 .gitignore 文件忽略。如果该目录被忽略，生成的文档将不会被推送到生产服务器，导致无法访问。
根据你的项目结构和需求，调整 -d 和 -t 参数。

步骤 2: 配置 Filesystem Disk

为了方便 Laravel 管理生成的文档，我们需要在 config/filesystem.php 文件中添加一个新的 disk 配置：

Calliper 文档对比神器

文档内容对比神器

查看详情

'disks' => [

    // ... other disks

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

登录后复制

这个配置定义了一个名为 local-docs 的 disk，它使用 local 驱动，并将根目录指向 storage/docs/。

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

接下来，我们需要创建一个路由来提供文档服务，并应用 auth 中间件来限制访问。在 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 (is_null($url)) {
        $url = 'index.html'; // Or your default doc page
    }
    if (!Storage::disk('local-docs')->exists($url)) {
        abort(404);
    }
    $resp = response(Storage::disk('local-docs')->get($url));
    $resp->header('content-type', MimeType::fromFilename($url));
    return $resp;

})->where('url', '(.*)')->middleware('auth');

登录后复制

这段代码定义了一个 /docs/{url?} 路由，它可以接收一个可选的 URL 参数。