Laravel普通网站项目文档自动生成替代方案咨询

Hey there! I’ve dealt with exactly this scenario—building docs for a non-API Laravel site when phpDocumentor felt like it wasn’t playing nice with the latest Laravel versions. Here are some solid alternatives and fixes that worked for me:

First: Double-Check phpDocumentor 3.x (It Probably Works!) #

Chances are you might have been using an older version of phpDocumentor that doesn’t support PHP 8+ (required by Laravel 9+). The latest phpDocumentor 3.x fully supports modern PHP and Laravel—you just need to configure it correctly to ignore Laravel’s boilerplate and focus on your code.

1. Install the latest dev version:

   composer require --dev phpdocumentor/phpdocumentor
   

2. Create a phpdoc.xml config file in your project root to tailor it to Laravel:

   <?xml version="1.0" encoding="UTF-8"?>
   <phpdocumentor configVersion="3">
       <paths>
           <output>docs/generated</output> <!-- Where docs will save -->
           <directory>app</directory> <!-- Your custom code -->
           <exclude>app/Http/Middleware</exclude> <!-- Skip boilerplate -->
           <exclude>app/Providers</exclude>
           <exclude>vendor</exclude>
       </paths>
       <transformer>
           <template>clean</template> <!-- Clean, readable theme -->
       </transformer>
   </phpdocumentor>
   

3. Run the generator:

   vendor/bin/phpdoc run
   

This will generate static HTML docs for your controllers, models, and custom classes—perfect for non-API sites where you want to document business logic and page functionality.

Custom Artisan Command + Doctrine PHPDoc Parser #

If you need full control over what gets documented (like linking controllers to views, page workflows, or custom business rules), build a simple Artisan command using Doctrine’s PHPDoc parser. It’s flexible and tailored exactly to your project.

1. Install the parser:

   composer require --dev doctrine/phpdoc-parser
   

2. Create a custom command (e.g., app/Console/Commands/GenerateProjectDocs.php):

   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use ReflectionClass;
   use ReflectionMethod;
   
   class GenerateProjectDocs extends Command
   {
       protected $signature = 'docs:generate';
       protected $description = 'Generate custom docs for our Laravel site';
   
       public function handle()
       {
           $docsPath = base_path('docs/project.md');
           $content = "# Our Site Documentation\n\n";
   
           // Parse controllers
           $this->parseControllers($content);
           // Add more sections (models, services) as needed
   
           file_put_contents($docsPath, $content);
           $this->info('Docs generated successfully at ' . $docsPath);
       }
   
       private function parseControllers(&$content)
       {
           $controllerDir = app_path('Http/Controllers');
           $content .= "## Page Controllers\n\n";
   
           foreach (glob("$controllerDir/*.php") as $file) {
               $className = 'App\\Http\\Controllers\\' . basename($file, '.php');
               $reflection = new ReflectionClass($className);
               $classDoc = $this->cleanDocComment($reflection->getDocComment());
   
               if (!empty($classDoc)) {
                   $content .= "### {$reflection->getShortName()}\n";
                   $content .= "{$classDoc}\n\n";
   
                   // Parse public methods (page actions)
                   foreach ($reflection->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
                       if (!$method->isConstructor()) {
                           $methodDoc = $this->cleanDocComment($method->getDocComment());
                           if (!empty($methodDoc)) {
                               $content .= "#### {$method->getName()}\n";
                               $content .= "{$methodDoc}\n\n";
                           }
                       }
                   }
               }
           }
       }
   
       private function cleanDocComment(?string $docComment): string
       {
           if (!$docComment) return '';
           // Strip PHPDoc tags and clean up formatting
           return trim(preg_replace(['/\/\*\*/', '/\*\//', '/^\*\s?/m'], '', $docComment));
       }
   }
   

3. Register the command in app/Console/Kernel.php (Laravel 10+ might auto-discover it), then run:

   php artisan docs:generate
   

You can extend this to add route info, view names, or any custom details your team needs—total flexibility.

Daux.io: Mix Auto-Generated + Manual Docs #

If you want a polished, searchable docs site that combines auto-generated code docs and hand-written guides (like setup instructions or user workflows), Daux.io is perfect. It turns Markdown into a beautiful static site, and you can pair it with phpDocumentor to import code comments.

1. Install Daux.io:

   composer require --dev daux/daux.io
   

2. Create a docs directory in your root. Add manual Markdown files (e.g., docs/setup.md, docs/user-guides.md) and use phpDocumentor to generate code docs into docs/api.
3. Run the Daux generator:

   vendor/bin/daux generate --output public/docs
   

This creates a fully navigable docs site at your-site.com/docs with search, responsive design, and customizable themes.

Honorable Mention: MkDocs with PHP Plugin #

For more complex documentation needs (like multi-version docs or advanced customization), MkDocs paired with the mkdocs-phpdoc-plugin lets you pull in code comments directly into your MkDocs structure. It’s a bit more setup, but great for larger projects.

内容的提问来源于stack exchange，提问作者korg