Php Codebrowser Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mayflower/php-codebrowser
   

   Add the service provider to config/app.php:

   Mayflower\CodeBrowser\CodeBrowserServiceProvider::class,
   

2. Basic Usage Generate a code browser for a single file:

   use Mayflower\CodeBrowser\CodeBrowser;
   
   $browser = new CodeBrowser();
   $browser->addFile('/path/to/YourClass.php');
   $browser->generate();
   

   Outputs to ./codebrowser/output/ by default.

3. First Use Case Quickly visualize a single class with:

   $browser->addFile(app_path('Http/Controllers/YourController.php'))
           ->withQATools(['phpstan', 'phpmd'])
           ->generate();
   

Implementation Patterns

Core Workflows

1. Bulk Processing Recursively scan a directory (e.g., app/):

   $browser->addDirectory(app_path())
           ->exclude('tests', 'vendor')
           ->generate();
   

2. QA Tool Integration Enable tools via config (config/codebrowser.php):

   'tools' => [
       'phpstan' => true,
       'phpmd'   => ['ruleset' => 'cleancode'],
       'phpcs'   => ['standard' => 'PSR12'],
   ],
   

   Or programmatically:

   $browser->withQATools(['phpstan', 'phpmd']);
   

3. Custom Output Override output path:

   $browser->setOutputPath(storage_path('codebrowser'));
   

   Or use a custom renderer:

   $browser->setRenderer(new Mayflower\CodeBrowser\Renderers\JsonRenderer());
   

4. CI/CD Integration Cache results for faster builds:

   $browser->cacheResults(3600); // Cache for 1 hour
   

Integration Tips

• Laravel Artisan Command Create a custom command:

  use Mayflower\CodeBrowser\CodeBrowser;
  
  class CodeBrowserCommand extends Command {
      protected $signature = 'codebrowser:generate {--path= : Path to analyze}';
      public function handle() {
          $browser = new CodeBrowser();
          $browser->addDirectory($this->option('path') ?? app_path());
          $browser->generate();
          $this->info('Code browser generated!');
      }
  }
  

• Event Listeners Trigger on codebrowser.generated event:

  event(new CodeBrowserGenerated($browser->getResults()));
  

• Dynamic Tool Configuration Use environment variables:

  $browser->withQATools(
      array_filter(['phpstan', 'phpmd'], fn($tool) => env("CODEBROWSER_{$tool}", true))
  );
  

Gotchas and Tips

Common Pitfalls

1. Tool Dependencies

   • Ensure required tools (e.g., phpstan, phpmd) are installed globally or via Composer.
   • Debug missing tools with:

     composer show mayflower/php-codebrowser
     

2. Performance

   • Large codebases may slow down generation. Use --parallel flag (if supported in future versions) or chunk directories:

     $browser->addDirectory(app_path('Http/Controllers'))
             ->addDirectory(app_path('Models'));
     

3. Path Handling

   • Use absolute paths for reliability:

     $browser->addFile(realpath(app_path('YourFile.php')));
     

   • Avoid symlinked directories (may cause duplicate entries).

4. QA Tool Conflicts

   • Disable tools if they conflict (e.g., phpstan and phpmd analyzing the same file twice).
   • Clear cache if tools update their output format:

     php artisan codebrowser:clear-cache
     

Debugging Tips

• Verbose Output Enable debug mode:

  $browser->setDebug(true);
  

  Or via config:

  'debug' => env('APP_DEBUG', false),
  

• Log Analysis Check storage/logs/codebrowser.log for tool-specific errors.

• Tool-Specific Quirks

  • PHPStan: Ensure phpstan.neon is configured for your project.
  • PHPMD: Specify a custom ruleset to avoid false positives:

    $browser->withQATools(['phpmd' => ['ruleset' => 'custom-ruleset.xml']]);
    

Extension Points

1. Custom QA Tools Implement Mayflower\CodeBrowser\Contracts\QATool:

   class CustomTool implements QATool {
       public function analyze(File $file): array {
           return ['issues' => $this->runCustomAnalysis($file)];
       }
   }
   

   Register via service provider:

   $this->app->bind(QATool::class, function() {
       return collect([new CustomTool()]);
   });
   

2. Renderer Extensions Extend Mayflower\CodeBrowser\Renderers\BaseRenderer to add custom output formats (e.g., Markdown, HTML tables).

3. Pre/Post-Processing Use events to modify results:

   CodeBrowser::generated(function ($results) {
       $results->each(fn($file) => $file->addCustomAnnotation('MyAnnotation'));
   });
   

4. Configuration Overrides Dynamically override tool settings:

   $browser->overrideToolConfig('phpstan', ['level' => 'max']);