Easy Doc Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev easycorp/easy-doc-bundle
   

   (Note: While this is a Symfony package, Laravel developers can use it via Symfony’s Console component or by integrating it into a custom command.)

2. Enable the Bundle (Laravel Adaptation):

   • Since Laravel doesn’t use AppKernel, create a custom Artisan command to trigger the documentation generation. Add this to app/Console/Commands/GenerateDoc.php:

     <?php
     namespace App\Console\Commands;
     use Illuminate\Console\Command;
     use EasyCorp\Bundle\EasyDocBundle\Command\DocCommand;
     
     class GenerateDoc extends Command
     {
         protected $signature = 'doc:generate';
         protected $description = 'Generate application documentation';
     
         public function handle()
         {
             $docCommand = new DocCommand();
             $docCommand->run(new \Symfony\Component\Console\Input\ArrayInput([]), new \Symfony\Component\Console\Output\ConsoleOutput());
         }
     }
     

   • Register the command in app/Console/Kernel.php:

     protected $commands = [
         \App\Console\Commands\GenerateDoc::class,
     ];
     

3. First Use Case: Run the command to generate documentation in public/docs/ (or a custom path):

   php artisan doc:generate
   

   • Open public/docs/index.html in a browser to view the generated documentation.

Implementation Patterns

Usage Patterns

1. Integrate with CI/CD:

   • Add the command to your deployment pipeline (e.g., GitHub Actions, GitLab CI) to auto-generate docs on every merge to main:

     # .github/workflows/docs.yml
     jobs:
       generate-docs:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v3
           - run: composer install --no-dev
           - run: php artisan doc:generate
           - uses: actions/upload-artifact@v3
             with:
               name: documentation
               path: public/docs/
     

2. Customize Output Path:

   • Override the default output directory by publishing the bundle’s config (Symfony-style) and updating easy_doc.yaml:

     # config/easy_doc.yaml
     output_dir: 'storage/app/docs'
     

3. Extend Documentation:

   • Add custom panels (e.g., for Laravel-specific features like Jobs, Events, or Policies) by extending the bundle’s Panel classes. Example:

     // app/EasyDoc/CustomPanel.php
     namespace App\EasyDoc;
     use EasyCorp\Bundle\EasyDocBundle\Panel\PanelInterface;
     
     class CustomPanel implements PanelInterface
     {
         public function getName(): string
         {
             return 'Laravel Jobs';
         }
     
         public function getContent(): string
         {
             return $this->renderJobsList();
         }
     }
     

   • Register the panel in a service provider:

     // app/Providers/EasyDocServiceProvider.php
     public function register()
     {
         $this->app->extend('easy_doc.panels', function ($panels) {
             $panels[] = new \App\EasyDoc\CustomPanel();
             return $panels;
         });
     }
     

4. Generate Docs on Demand:

   • Trigger documentation generation via a route (e.g., for admin panels):

     // routes/web.php
     Route::get('/admin/docs', function () {
         Artisan::call('doc:generate');
         return redirect()->to('/docs/index.html');
     });
     

Workflows

• Onboarding New Developers:

  • Point team members to the auto-generated public/docs/index.html for a high-level overview of routes, services, and bundles.
  • Use the bundles panel (v1.1.1+) to explain dependency structure and potential conflicts.

• Debugging:

  • Cross-reference the generated docs with errors (e.g., a missing service in routes or a deprecated bundle in the bundles panel).

• Client Deliverables:

  • Zip the public/docs/ directory and include it in project handoffs for transparency.

Integration Tips

• Symfony Components:
  • Leverage Symfony’s HttpKernel or DependencyInjection components if you need deeper integration (e.g., for dynamic panel content).
• Laravel Mix:
  • Process the generated HTML through Laravel Mix for minification or versioning:

    // webpack.mix.js
    mix.copy('public/docs', 'public/docs-built');
    

• Storage:
  • Store docs in cloud storage (e.g., S3) by extending the output logic:

    // Override EasyDocBundle's output handler
    $this->app->bind('easy_doc.output_handler', function () {
        return new \App\Services\S3OutputHandler();
    });
    

Gotchas and Tips

Pitfalls

1. Symfony Dependency:

   • The bundle assumes Symfony’s Kernel and Console components. If you encounter issues, ensure compatibility by:
     • Using symfony/console and symfony/http-kernel as dev dependencies:

       composer require --dev symfony/console symfony/http-kernel
       

     • Mocking Symfony’s Application class in your custom command if needed.

2. Outdated Releases:

   • The last release was in 2017, so expect limited Laravel-specific features. Test thoroughly in a staging environment.
   • Fork the repository and update dependencies (e.g., Symfony 5/6) if critical features are missing.

3. Performance:

   • Documentation generation can be slow for large applications. Cache the output or generate docs incrementally:

     // Cache the generated HTML for 1 hour
     $content = Cache::remember('easy_doc_html', 3600, function () {
         return $this->generateDocContent();
     });
     

4. Template Overrides:

   • Customizing templates requires overriding the bundle’s Twig templates. Place overrides in:

     resources/views/vendor/easy_doc/
     

   • Clear Laravel’s view cache afterward:

     php artisan view:clear
     

Debugging

• Command Errors:

  • Run the command with verbose output to diagnose issues:

    php artisan doc:generate --verbose
    

  • Check Symfony’s Input/Output handling if the command fails silently.

• Missing Panels:

  • Ensure panels are registered in the easy_doc.panels service. Use Laravel’s bind() method (as shown above) to inject custom panels.

• Bundle Not Found:

  • If the bundle isn’t detected, verify:
    • The EasyDocBundle is loaded in your AppServiceProvider or a dedicated service provider.
    • The AppKernel-style registration is adapted to Laravel’s autoloading.

Tips

1. Laravel-Specific Panels:

   • Create panels for Laravel features like:
     • Routes: Extend the existing routes panel to include Laravel’s route model binding or API resource docs.
     • Middleware: List all middleware with their priority and namespace.
     • Service Providers: Document boot methods and bindings.

2. Version Control:

   • Commit the generated public/docs/ to your repository for consistency, but exclude it from CI/CD pipelines to avoid bloating artifacts. Use .gitignore:

     public/docs/
     !public/docs/.gitkeep
     

3. Dynamic Content:

   • Fetch real-time data (e.g., database schema, queue jobs) by extending panels:

     public function getContent(): string
     {
         $jobs = \DB::table('jobs')->get();
         return $this->twig->render('EasyDocBundle:Panel:jobs.html.twig', ['jobs' => $jobs]);
     }
     

4. Localization:

   • Override the bundle’s translation files (located in vendor/easycorp/easy-doc-bundle/Resources/translations/) for multilingual docs.

5. Security:

   • Restrict access to generated docs in production by:
     • Adding middleware to the /docs route:

       Route::middleware(['auth'])->get('/docs/{path}', function ($path) {
           return file_get_contents(public_path("docs/{$path}"));
       });
       

     • Or serving docs via a signed URL (e.g., using Laravel’s temporaryUrl() for S3).