Php Doc Fill Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require appventus/php-doc-fill-bundle:dev-master
   

2. Register the Bundle in app/AppKernel.php:

   public function registerBundles() {
       return [
           // ...
           new AppVentus\PhpDocFillBundle\AvPhpDocFillBundle(),
       ];
   }
   

3. Enable PHP Templating in config.yml:

   framework:
       templating:
           engines: ['twig', 'php']
   

4. Add Routing in app/config/routing.yml:

   av_php_doc_fill_bundle_routes:
       resource: "@AvPhpDocFillBundle/Resources/config/routing.yml"
       prefix:   /
   

First Use Case

• Debug Bar Integration: The bundle adds a new tab to the Symfony2 Debug Toolbar (under "PHP Doc Fill").
  • Clicking it reveals a UI to generate or update PHPDoc blocks for classes/methods.
  • Useful for quickly scaffolding documentation during development.

Implementation Patterns

Workflow Integration

1. Onboarding New Developers:

   • Use the Debug Toolbar UI to auto-generate PHPDoc blocks for controllers/services.
   • Example: Generate @param and @return tags for a service method:

     /**
      * @param User $user The authenticated user
      * @return Response JSON response
      */
     public function getUserData(User $user) { ... }
     

2. CI/CD Pipeline:

   • Integrate with static analysis tools (e.g., PHPStan, Psalm) to enforce PHPDoc compliance.
   • Example .phpstan.neon rule:

     parameters:
         level: 5
         checkMissingIterableValueType: true
     

3. Template-Based Generation:

   • Extend the bundle’s templating to enforce custom docblock formats (e.g., adding @throws for exceptions).
   • Override AvPhpDocFillBundle/Resources/views/ templates in your project.

Common Use Cases

• Controller Documentation: Generate PHPDoc for route handlers to auto-document API endpoints.

  /**
   * @Route("/api/users", name="get_users", methods={"GET"})
   * @param Request $request
   * @return JsonResponse List of users
   */
  public function index(Request $request) { ... }
  

• Service Layer: Use the bundle to document dependencies and return types for better IDE support (e.g., PhpStorm autocompletion).

• Legacy Code Refactoring: Run the bundle’s CLI tool (if available) to batch-generate PHPDoc for large codebases:

  php bin/console av:phpdoc:generate src/Entity
  

Gotchas and Tips

Pitfalls

1. Debug Toolbar Dependency:

   • The bundle only works with the Symfony Debug Toolbar. Disable it in production (APP_DEBUG=false).
   • Workaround: Use the underlying phpdocfill/phpdocfill library directly for CLI generation.

2. Template Engine Requirement:

   • PHP templating engine must be enabled ('php' in framework.templating.engines). Missing this breaks the UI.

3. No CLI Tool:

   • The bundle lacks a standalone CLI command (unlike the original phpdocfill library). Use:

     vendor/bin/phpdocfill generate src/ --format=php
     

4. Symfony 2.x Only:

   • Not compatible with Symfony 3+/4+/5+. Migrate to phpdocfill/phpdocfill for newer versions.

Debugging

• Blank Debug Toolbar Tab: Check app/logs/dev.log for errors. Common causes:

  • Missing php engine in templating.engines.
  • Incorrect bundle registration (e.g., typo in AppKernel.php).

• Generated PHPDoc Issues: Manually edit templates in app/Resources/AvPhpDocFillBundle/views/ to customize output (e.g., add @author tags).

Extension Points

1. Custom Docblock Templates: Override the default template at app/Resources/AvPhpDocFillBundle/views/default/docblock.php.twig.

2. Exclude Directories: Configure excluded paths in config.yml (if supported):

   av_php_doc_fill:
       exclude_dirs: ["src/Tests", "vendor"]
   

3. Integration with IDEs: Use generated PHPDoc to enable:

   • PhpStorm’s "Go to Implementation" for return types.
   • VSCode’s PHP Intelephense for parameter hints.

Pro Tips

• Pair with PHPStan: Enforce PHPDoc accuracy by adding rules like:

  # phpstan.neon
  parameters:
      checkReturnTypeAgainstReturnTag: true
  

• Git Hooks: Add a pre-commit hook to validate PHPDoc blocks using phpdocfill validate.

• Legacy Code: Use the bundle to incrementally document classes, then refine manually:

  # Generate docs for a single class
  vendor/bin/phpdocfill generate src/Entity/User.php --format=php