PHP数据库文档怎么自动生成

wen PHP项目 2026-07-04 18

本文目录导读：

PHP数据库文档怎么自动生成

使用数据库文档生成工具
Laravel专属工具
自定义PHP脚本
使用ORM注释生成文档
集成到CI/CD
推荐的完整解决方案
在线工具
最佳实践

我来介绍几种PHP数据库文档自动生成的方法和工具：

使用数据库文档生成工具

SchemaSpy（推荐）

最流行的数据库文档生成工具：

# 安装
brew install schemaspy
# 生成文档
java -jar schemaspy.jar \
  -t mysql \
  -db database_name \
  -host localhost \
  -port 3306 \
  -u root \
  -p password \
  -o ./docs

DBDoc

简单的PHP工具：

// 使用 DBDoc
composer require cytopia/dbdoc
// 配置
$dbConfig = [
    'host' => 'localhost',
    'database' => 'test_db',
    'username' => 'root',
    'password' => 'password'
];
$dbDoc = new DBDoc\DBDoc();
$dbDoc->generate($dbConfig, './docs');

Laravel专属工具

Laravel-DevTools

composer require --dev bavix/laravel-dev-tools
php artisan make:database-documentation

Laravel-ER-Diagram

composer require --dev beyondcode/laravel-er-diagram-generator
# 生成ER图
php artisan er:generate

自定义PHP脚本

基于PDO的文档生成器

<?php
class DatabaseDocumentGenerator
{
    private $pdo;
    public function __construct($host, $dbname, $user, $pass)
    {
        $this->pdo = new PDO("mysql:host=$host;dbname=$dbname", $user, $pass);
    }
    public function generateMarkdown()
    {
        $tables = $this->getTables();
        $markdown = "# 数据库文档\n\n";
        foreach ($tables as $table) {
            $markdown .= "## {$table}\n\n";
            $columns = $this->getColumns($table);
            $markdown .= "| 字段 | 类型 | 是否为空 | 默认值 | 注释 |\n";
            $markdown .= "|------|------|----------|--------|------|\n";
            foreach ($columns as $col) {
                $markdown .= "| {$col['Field']} | {$col['Type']} | ";
                $markdown .= "{$col['Null']} | {$col['Default']} | ";
                $markdown .= "{$col['Comment']} |\n";
            }
            $markdown .= "\n";
        }
        file_put_contents('database-doc.md', $markdown);
        return $markdown;
    }
    private function getTables()
    {
        $stmt = $this->pdo->query("SHOW TABLES");
        return $stmt->fetchAll(PDO::FETCH_COLUMN);
    }
    private function getColumns($table)
    {
        $stmt = $this->pdo->query("SHOW FULL COLUMNS FROM `$table`");
        return $stmt->fetchAll(PDO::FETCH_ASSOC);
    }
}
// 使用
$doc = new DatabaseDocumentGenerator('localhost', 'test_db', 'root', 'password');
$doc->generateMarkdown();

使用ORM注释生成文档

DocBlock解析器

<?php
/**
 * @Entity @Table(name="users")
 **/
class User
{
    /** 
     * @Id 
     * @Column(type="integer")
     * @GeneratedValue 
     **/
    protected $id;
    /** 
     * @Column(type="string", length=100)
     * @var string 用户名
     **/
    protected $username;
}
// 生成文档
class ORMDocGenerator
{
    public function generate($entities)
    {
        $doc = "# ORM数据库文档\n\n";
        foreach ($entities as $entity) {
            $reflection = new ReflectionClass($entity);
            $doc .= "## {$reflection->getShortName()}\n\n";
            foreach ($reflection->getProperties() as $property) {
                $docComment = $property->getDocComment();
                preg_match('/@var\s+(\S+)\s+(.+)/', $docComment, $matches);
                $doc .= "- **{$property->getName()}**: ";
                $doc .= isset($matches[2]) ? $matches[2] : "无描述";
                $doc .= " ({$matches[1]})\n";
            }
            $doc .= "\n";
        }
        file_put_contents('orm-doc.md', $doc);
        return $doc;
    }
}

集成到CI/CD

GitLab CI配置

generate-db-docs:
  stage: deploy
  script:
    - composer install
    - php artisan db:doc:generate
    - cp docs/* public/docs/
  artifacts:
    paths:
      - public/docs/

GitHub Actions

name: Generate DB Docs
on: [push]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: shogo82148/actions-setup-mysql@v1
      - name: Generate docs
        run: |
          composer install
          php generate-doc.php
      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs