Surveyor Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: Surveyor excels as a pre-build static analysis tool, fitting seamlessly into Laravel’s ecosystem by leveraging PHP’s AST (Abstract Syntax Tree) for deep code inspection. It aligns with modern CI/CD pipelines (e.g., GitHub Actions, GitLab CI) for pre-commit or pre-deploy validation.
• Metadata Extraction: Provides structured DTOs (Data Transfer Objects) for classes, methods, properties, and Laravel-specific constructs (e.g., Eloquent models, routes, middleware). This enables downstream use cases like:
  • Documentation generation (e.g., API specs, Swagger/OpenAPI).
  • Custom linting/rules engines (e.g., enforcing naming conventions, return type consistency).
  • Dependency mapping (e.g., identifying circular dependencies, unused classes).
• Complement to Ranger: Acts as a foundational layer for Laravel Ranger, which builds on Surveyor’s output for higher-level analysis (e.g., security scans, performance profiling).

Integration Feasibility

• Low-Coupling Design: Surveyor operates as a standalone analyzer with no runtime dependencies, making it ideal for:
  • Pre-commit hooks (via composer exec or custom scripts).
  • CI/CD pipelines (e.g., fail builds if critical issues are detected).
  • Local development (IDE plugins or CLI tools).
• PHP 8.1+ Compatibility: Requires modern PHP features (e.g., attributes, named arguments), which may necessitate upgrading legacy Laravel apps (v7.x or earlier).
• Laravel-Specific Focus: Optimized for Laravel’s conventions (e.g., service providers, Facades, Blade templates), but can analyze vanilla PHP projects with limited Laravel-specific features.

Technical Risk

• Beta Stage: API instability (pre-v1.0) may require frequent updates or custom wrappers to handle breaking changes. Mitigation:
  • Pin to a specific beta version in composer.json.
  • Monitor the changelog for deprecations.
• Performance Overhead: Static analysis of large codebases (e.g., 10K+ files) may introduce CI/CD slowdowns. Risk mitigation:
  • Cache results (e.g., store parsed metadata in a database or JSON file).
  • Run incrementally (e.g., only analyze changed files).
• False Positives/Negatives: Custom rules may misclassify code due to Laravel’s dynamic nature (e.g., dynamic method calls, magic methods). Validation required for production use.

Key Questions

1. Use Case Clarity:
   • Is Surveyor needed for code quality, documentation, or custom tooling? If the latter, will Ranger suffice, or are raw DTOs required?
   • Are there existing tools (ephpdoc, Psalm, PHPStan) already fulfilling similar needs?
2. Laravel Version Support:
   • What’s the target Laravel version? Surveyor’s Laravel-specific features may not work on older versions (e.g., <8.0).
3. Output Consumption:
   • How will Surveyor’s DTOs be used? Direct API consumption, or integration with other tools (e.g., Docusaurus, custom dashboards)?
4. CI/CD Integration:
   • Where in the pipeline will Surveyor run? Pre-commit, post-test, or pre-deploy?
   • Are there budget/time constraints for handling false positives or performance bottlenecks?
5. Maintenance Plan:
   • Who will monitor Surveyor’s API changes and update the integration?
   • Is there a fallback plan if Surveyor reaches end-of-life?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem: Native fit for Laravel projects (v8.0+). Compatible with:
  • Composer: Standard require installation.
  • PHP 8.1+: Required for attributes and other modern features.
  • Laravel-Specific Features: Best results for projects using Eloquent, Facades, Blade, and service providers.
• Tooling Compatibility:
  • CI/CD: Works with GitHub Actions, GitLab CI, CircleCI (via composer exec or custom scripts).
  • IDE Plugins: Could integrate with PHPStorm/VSCode via custom language servers.
  • Databases: Output DTOs can be stored in SQLite, MySQL, or Elasticsearch for querying.
• Alternatives Considered:
  • ephpdoc: Lighter but lacks Laravel-specific analysis.
  • Psalm/PHPStan: Stronger typing but less Laravel-aware.
  • Custom AST Parsers: More control but higher maintenance.

Migration Path

1. Pilot Phase:
   • Install Surveyor in a non-production environment (e.g., staging).
   • Run against a subset of the codebase (e.g., /app/Http/Controllers).
   • Validate output DTOs match expectations (e.g., class hierarchies, method signatures).
2. Incremental Rollout:
   • Phase 1: Use Surveyor for documentation generation (e.g., auto-generate API docs from route/controller metadata).
   • Phase 2: Integrate into CI/CD as a pre-commit check (e.g., fail if undefined methods are called).
   • Phase 3: Build custom rules (e.g., "no business logic in controllers") using Surveyor’s DTOs.
3. Fallback Plan:
   • If Surveyor’s API changes break integrations, maintain a local fork or switch to Ranger for higher-level needs.

Compatibility

• Laravel Versions:
  • Supported: v8.0+ (full Laravel-specific features).
  • Partial: v7.x (limited support; may miss newer Laravel constructs).
  • Unsupported: v6.x or earlier (PHP 8.1+ requirement).
• PHP Extensions: No hard dependencies, but some Laravel features (e.g., OPcache) may affect performance.
• Monorepos/Polyrepos: Surveyor can analyze multiple projects if configured to scan specific directories.

Sequencing

1. Pre-Installation:
   • Upgrade PHP to 8.1+ if not already done.
   • Ensure Laravel is v8.0+ for full feature support.
   • Review the changelog for breaking changes in the target beta version.
2. Installation:

   composer require laravel/surveyor --dev
   

   • Add to composer.json scripts for CI/CD:

     "scripts": {
       "survey": "vendor:bin/surveyor"
     }
     

3. Configuration:
   • Customize via .surveyor.php (if needed) to exclude directories or focus on specific file types.
4. CI/CD Integration:
   • Example GitHub Actions workflow:

     - name: Run Surveyor
       run: composer survey
     - name: Fail on warnings
       if: contains(steps.survey.outputs.result, 'warning')
       run: exit 1
     

5. Post-Deployment:
   • Monitor Surveyor’s output for false positives/negatives.
   • Iterate on custom rules or documentation templates.

Operational Impact

Maintenance

• Dependency Updates:
  • Pin to a specific beta version to avoid unexpected API changes.
  • Set up Composer notifications for Surveyor updates.
• Custom Rules:
  • Maintain a local library of Surveyor-based rules (e.g., in a private repo or monorepo).
  • Document assumptions about Surveyor’s output format.
• Forking Strategy:
  • If Surveyor reaches v1.0, evaluate whether to migrate to the stable version or maintain a fork for critical customizations.

Support

• Troubleshooting:
  • Common issues:
    • False positives: Validate against manual code reviews.
    • Performance: Profile with composer survey --profile and optimize CI/CD caching.
    • Laravel-specific quirks: Surveyor may misparse dynamic code (e.g., app()->make()). Test edge cases.
  • Community Resources:
    • GitHub Discussions, Laravel Slack (#packages), or Stack Overflow ([laravel-surveyor] tag).
• Vendor Lock-in:
  • Surveyor’s DTO structure is not standardized, so custom tooling may break with API changes. Mitigate by:
    • Abstracting Surveyor behind a local adapter layer.
    • Exporting DTOs to a stable format (e.g., JSON Schema) for downstream tools.

Scaling

• Performance:
  • Large Codebases: Surveyor may take minutes to analyze 10K+ files. Mitigations:
    • Incremental Analysis: Only scan changed files (e.g., using git diff).
    • Caching: Store parsed results in a database or JSON file (e.g.,