Weave Code
Surveyor Laravel Package
laravel/surveyor
Beta Laravel tool for mostly static analysis of PHP/Laravel apps. Parses files/classes to extract rich metadata (classes, methods, properties, types) and can inspect models and container bindings for extra detail. Returns structured results for other tools.
Laravel Surveyor is a powerful (mostly) static analysis tool designed to extract detailed PHP and Laravel-specific information from your code.
Frequently asked questions about Surveyor
- How does Laravel Surveyor differ from PHPStan or Psalm for static analysis?
- Surveyor specializes in Laravel-specific constructs (Eloquent models, routes, middleware) and generates structured DTOs for downstream tools like Ranger. While PHPStan/Psalm handle general PHP, Surveyor’s Laravel focus and recent inline array assignment fixes make it ideal for Blade templates or dynamic configs where those tools may miss context.
- Can I use Surveyor in a pre-commit Git hook for Laravel projects?
- Yes, Surveyor is designed for pre-commit/pre-deploy validation. Run it via `composer exec surveyor` in your hook script. The tool’s lightweight CLI integration makes it perfect for catching issues like undefined array keys or unused inline variables before they reach CI.
- Does Surveyor support Laravel versions below 8.0?
- No, Surveyor requires Laravel 8.0+ and PHP 8.1+. The inline array assignment fix (PR #30) specifically targets Laravel’s Blade templates and dynamic configurations, which rely on newer PHP features. Legacy apps will need alternative tools like Psalm or custom AST parsers.
- How can I use Surveyor’s output for auto-generating API documentation?
- Surveyor extracts rich metadata (methods, return types, array structures) into DTOs. Pipe these to tools like Swagger or custom scripts to auto-generate docs. For example, use `$result->result()` to access class/method details, then map them to OpenAPI schemas or Markdown templates.
- Will Surveyor slow down my CI/CD pipeline significantly?
- Performance is a known limitation—Surveyor can be slow for large codebases. Mitigate this by caching results (store outputs in JSON/DB) or running incrementally (e.g., only analyze changed files). For critical pipelines, test with a sample of Blade-heavy files first to gauge impact.
- Can Surveyor detect circular dependencies in Laravel service providers?
- Yes, Surveyor inspects container bindings and can identify circular dependencies involving array-based configurations (e.g., `$app->bind('key', fn() => new ClassThatDependsOn('key'))`). The refined AST parsing improves accuracy for dynamic bindings, though manual validation is still recommended for production.
- How do I integrate Surveyor with Laravel Ranger?
- Surveyor acts as a foundational layer for Ranger. Install both packages, then use Surveyor’s DTOs (e.g., `$analyzer->analyze()`) as input for Ranger’s higher-level analyses. Ranger builds on Surveyor’s metadata to detect issues like unused middleware or invalid route parameters.
- Does Surveyor handle Blade templates with inline PHP arrays?
- Yes, the recent fix for inline array assignments (e.g., `@php $config = ['key' => $value] @endphp`) improves parsing of Blade templates. Surveyor now accurately extracts metadata from dynamic array configurations, reducing false negatives in static analysis for views.
- What’s the best way to test Surveyor’s accuracy in my project?
- Start with a small subset of files (e.g., Blade templates or service providers with array bindings) and compare Surveyor’s output against manual reviews. Use the CLI to analyze specific files (`composer exec surveyor analyze path/to/File.php`) and validate the DTO structure matches expectations.
- Are there alternatives if Surveyor’s API changes before v1.0?
- Pin to `0.1.10` in `composer.json` to lock the API. For long-term stability, consider Psalm or PHPStan for general PHP analysis, though they lack Laravel-specific context. If you need Surveyor’s features, monitor the changelog and plan a migration path post-v1.0.
Weaver
How can I help you explore Laravel packages today?