Surveyor Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/surveyor
   

   No additional configuration is required for basic usage.

2. First Use Case: Run Surveyor on a directory (e.g., app/) to extract metadata:

   use Laravel\Surveyor\Surveyor;
   
   $surveyor = new Surveyor();
   $results = $surveyor->survey(app_path('Http/Controllers'));
   

   This returns an array of Surveyor\Result objects, each representing a parsed PHP file.

3. Where to Look First:

   • Surveyor class: Core entry point for analysis.
   • Result class: Contains parsed metadata (e.g., classes, methods, properties).
   • Surveyor::survey(): Primary method to trigger analysis.
   • Surveyor::getResults(): Retrieve raw results (useful for debugging).

Implementation Patterns

Core Workflows

1. Surveying a Directory:

   $results = Surveyor::survey(base_path('app'));
   foreach ($results as $result) {
       // Access parsed data: $result->classes, $result->methods, etc.
   }
   

2. Filtering Results: Use Surveyor::filter() to narrow results (e.g., by namespace or class name):

   $filtered = $results->filter(fn ($result) => str_contains($result->namespace, 'App\\Http\\Controllers'));
   

3. Extracting Specific Metadata: Access structured data directly:

   foreach ($results as $result) {
       $methods = $result->methods->where('isPublic', true);
       $properties = $result->properties->where('isStatic', false);
   }
   

4. Integration with Laravel Ranger: For high-level DTOs, pair with laravel/ranger:

   use Laravel\Ranger\Ranger;
   
   $ranger = new Ranger();
   $ranger->analyze($results); // Convert Surveyor results to Ranger DTOs
   

Integration Tips

• Artisan Command: Create a custom command to run Surveyor periodically (e.g., during CI):

  use Laravel\Surveyor\Surveyor;
  use Symfony\Component\Console\Command\Command;
  
  class SurveyCommand extends Command {
      protected function handle() {
          $results = Surveyor::survey(app_path());
          // Log or process results...
      }
  }
  

• Event Listeners: Trigger Surveyor on file changes (e.g., via file:updated events) to keep metadata fresh.

• Caching: Cache results for performance (e.g., in bootstrap/cache):

  $cacheKey = 'surveyor_results';
  $results = Cache::remember($cacheKey, now()->addHours(1), fn () => Surveyor::survey(app_path()));
  

Gotchas and Tips

Pitfalls

1. Beta API Instability:

   • The API may change before v1.0.0. Check the changelog for breaking changes.
   • Workaround: Pin the package version in composer.json (e.g., ^0.1.0) to avoid unexpected updates.

2. Performance with Large Codebases:

   • Surveyor is not optimized for real-time analysis of thousands of files. Use caching or run during off-peak hours.
   • Tip: Exclude directories like vendor/ or storage/ to speed up analysis:

     $surveyor = new Surveyor(['exclude' => ['vendor', 'storage']]);
     

3. False Positives in Parsing:

   • Surveyor may misinterpret dynamic code (e.g., eval(), create_function()). Avoid relying on its output for such cases.
   • Tip: Manually verify critical results (e.g., method signatures) in edge cases.

4. Namespace Resolution:

   • Surveyor may not resolve namespaces correctly if autoloading is misconfigured. Ensure composer dump-autoload is up to date.

Debugging

• Enable Verbose Output: Pass ['verbose' => true] to the Surveyor constructor to log parsing details:

  $surveyor = new Surveyor(['verbose' => true]);
  

• Inspect Raw Results: Use Surveyor::getRawResults() to debug parsing issues:

  $rawResults = Surveyor::getRawResults();
  dd($rawResults); // Inspect the underlying data structure.
  

Extension Points

1. Custom Analyzers: Extend Surveyor by creating custom analyzers (e.g., to detect deprecated methods):

   use Laravel\Surveyor\Contracts\Analyzer;
   
   class DeprecationAnalyzer implements Analyzer {
       public function analyze($result) {
           foreach ($result->methods as $method) {
               if (str_contains($method['docComment'], '@deprecated')) {
                   // Trigger a warning or log the issue.
               }
           }
       }
   }
   

   Register the analyzer via the Surveyor constructor:

   $surveyor = new Surveyor(['analyzers' => [new DeprecationAnalyzer()]]);
   

2. Post-Processing: Use Laravel collections to transform results:

   $controllers = $results->flatMap->classes
       ->where('name', 'ends_with', 'Controller')
       ->pluck('methods');
   

3. Integration with Static Analysis Tools: Export Surveyor results to JSON for use with other tools (e.g., SonarQube):

   file_put_contents(
       storage_path('app/surveyor_results.json'),
       json_encode($results->toArray())
   );
   

Config Quirks

• Exclusion Patterns: Use glob patterns to exclude files/directories:

  $surveyor = new Surveyor(['exclude' => ['tests/*', 'app/Console/*']]);
  

• File Extensions: Surveyor defaults to .php files. To include other extensions (e.g., .inc), pass:

  $surveyor = new Surveyor(['extensions' => ['php', 'inc']]);