Surveyor Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis for Laravel: Surveyor is a Laravel-first static analysis tool, making it a natural fit for PHP/Laravel-based applications. It extracts structured metadata (classes, methods, properties, types) in a DTO-driven format, enabling downstream tooling (e.g., IDE plugins, code generators, or Laravel Ranger).
• Complementary to Existing Tools: Unlike traditional static analyzers (e.g., PHPStan, Psalm), Surveyor focuses on Laravel-specific constructs (Eloquent models, Facades, Inertia props, etc.), bridging gaps in generic PHP analyzers.
• Extensible Type System: The comprehensive type system (including Laravel-specific types like ArrayShapeType for Laravel collections) allows for fine-grained code introspection, useful for:
  • Code generation (e.g., API clients, DTOs).
  • Runtime validation (e.g., enforcing type contracts).
  • Documentation tools (e.g., auto-generating API docs).

Integration Feasibility

• Low Friction for Laravel Apps: Designed for Laravel, Surveyor integrates via Composer and Service Container, requiring minimal boilerplate.
• Non-Invasive: Operates as a library (not a framework), allowing selective adoption (e.g., analyze only critical paths).
• Dependency on Laravel: Requires a Laravel application (or at least the Laravel Service Provider system) to resolve bindings and Facades. Non-Laravel PHP projects would need significant adaptation.

Technical Risk

• Beta Stage: API is subject to change before v1.0.0, introducing backward compatibility risks for production use.
• Performance Overheads:
  • Memory-intensive: Static analysis of large codebases may stress memory (acknowledged in the README).
  • Database Inspection: Model analysis requires brief DB connections, which could fail in headless environments or cause latency.
• Caching Complexity: Cache invalidation relies on file modification tracking, which may fail in distributed or ephemeral environments (e.g., serverless).
• False Positives/Negatives: As a mostly static tool, it may miss runtime behaviors (e.g., dynamic class loading, magic methods).

Key Questions

1. Use Case Clarity:
   • Is Surveyor being adopted for code introspection, tooling, or runtime enforcement? (e.g., generating API clients vs. validating types at runtime).
   • Will the output be consumed by human developers (docs) or machine tools (codegen)?
2. Stability Needs:
   • Can the team tolerate beta-stage API changes, or is a stable v1.0 required?
   • Are there critical paths where analysis failures would break workflows?
3. Performance Tradeoffs:
   • How large is the codebase? Will memory usage or analysis time be prohibitive?
   • Can caching be optimized (e.g., Redis instead of disk)?
4. Environment Compatibility:
   • Will the tool run in CI/CD, local dev, or production? (DB connections may fail in headless environments.)
   • Are there non-Laravel dependencies (e.g., custom Facades) that Surveyor might misanalyze?
5. Maintenance Plan:
   • Who will monitor changelogs and adapt to breaking changes?
   • Is there a fallback if Surveyor fails (e.g., manual inspection)?

Integration Approach

Stack Fit

• Primary Use Case: Best suited for Laravel monoliths or large codebases where static analysis can unlock:
  • Code generation (e.g., OpenAPI specs from Laravel controllers).
  • Runtime validation (e.g., enforcing return types in services).
  • IDE/Editor plugins (e.g., autocompletion for Laravel-specific methods).
• Complementary Tools:
  • Laravel Ranger: For high-level consumption of Surveyor’s DTOs.
  • PHPStan/Psalm: For generic PHP static analysis (Surveyor fills Laravel gaps).
  • Laravel Pint/Laravel IDE Helper: For code formatting and IDE metadata.
• Non-Laravel Projects: Requires significant customization (e.g., mocking Laravel bindings).

Migration Path

1. Pilot Phase:
   • Start with non-critical paths (e.g., analyzing a single module).
   • Use caching (SURVEYOR_CACHE_ENABLED=true) to mitigate performance costs.
   • Validate output accuracy against manual inspection.
2. Gradual Rollout:
   • Integrate into CI/CD as a pre-commit hook or nightly job (not blocking).
   • Expose results via API (e.g., /api/code-analysis) for downstream tools.
3. Production Readiness:
   • Monitor cache hit/miss ratios and memory usage.
   • Implement fallbacks (e.g., skip analysis if DB is unreachable).

Compatibility

• Laravel Version: Tested against Laravel 10+ (assume compatibility with newer versions).
• PHP Version: Likely requires PHP 8.1+ (due to modern type system features).
• Dependencies:
  • Database: Only for model analysis (can be disabled if not needed).
  • File System: For caching (customizable via SURVEYOR_CACHE_DIR).
• Edge Cases:
  • Dynamic Proxies (e.g., Eloquent): Surveyor handles these but may need tuning.
  • Custom Macros/Facades: May require manual type hints for accurate analysis.

Sequencing

1. Setup:
   • Install via Composer: composer require laravel/surveyor.
   • Configure caching: .env + AnalyzedCache::enableDiskCache().
2. Basic Analysis:
   • Analyze a class: $analyzer->analyzeClass(\App\Models\User::class).
   • Validate output structure (e.g., ClassLikeResult methods).
3. Advanced Use Cases:
   • Model-Specific Analysis: Leverage isModelRelation(), databaseAttributes().
   • Type System: Use Type::from() for custom type checks.
4. Integration:
   • Expose results to other tools (e.g., Laravel Ranger, custom CLI).
   • Add to CI pipeline (e.g., fail builds on critical issues).

Operational Impact

Maintenance

• Changelog Monitoring: Critical due to beta-stage API. Assign a tech lead to track updates.
• Cache Management:
  • Disk Cache: Prune stale entries (e.g., via AnalyzedCache::clear()).
  • Memory Cache: Clear between analyses if needed (AnalyzedCache::clearMemory()).
• Dependency Updates: Surveyor relies on Laravel internals (e.g., Facade resolution). Major Laravel upgrades may require Surveyor updates.

Support

• Debugging:
  • False Positives: Surveyor may misanalyze dynamic code (e.g., eval, create_function). Document known limitations.
  • Performance Issues: Profile with large codebases (e.g., 10K+ files). Consider parallel analysis.
• Error Handling:
  • Database Failures: Wrap model analysis in try-catch if DB is optional.
  • File System Issues: Handle SURVEYOR_CACHE_DIR unavailability gracefully.
• Community Support: Limited to GitHub issues and Laravel Discord. May need internal runbooks.

Scaling

• Performance Bottlenecks:
  • Memory: Analyze one file/class at a time for large projects. Use queue workers for batch processing.
  • Time: Cache aggressively. Consider incremental analysis (e.g., only re-analyze changed files).
• Distributed Environments:
  • Cache Sharing: Use Redis instead of disk for distributed teams.
  • Analysis Isolation: Run in separate processes to avoid memory contention.
• CI/CD Impact:
  • Build Time: Add as a parallel job (not blocking). Set timeout thresholds.
  • Artifact Storage: Cache results between runs to avoid redundant work.

Failure Modes