Surveyor Laravel Package

Product Decisions This Supports

• Codebase Introspection & Tooling: Enables building internal developer tools (e.g., IDE plugins, auto-generated documentation, or API clients) by programmatically querying Laravel code structure.
• Static Analysis Pipeline: Integrates with CI/CD for pre-commit checks (e.g., validating method signatures, return types, or deprecated usage) without external tools like PHPStan.
• Dynamic Documentation: Powers auto-generated API docs (e.g., Swagger/OpenAPI) or IDE hints by extracting metadata from classes/methods.
• Build vs. Buy: Avoids reinventing static analysis wheels; leverages Laravel’s ecosystem for consistency.
• Use Cases:
  • Code Quality: Detect unused methods/properties or enforce naming conventions.
  • Migration Tools: Analyze breaking changes in refactoring (e.g., "Which classes use this deprecated method?").
  • Testing: Generate test stubs or mocks from class signatures.
  • Laravel-Specific Features: Extract Eloquent model relationships, cast types, or validation rules for downstream tools.

When to Consider This Package

• Adopt if:
  • Your team maintains a large Laravel codebase needing introspection (e.g., monoliths, shared libraries).
  • You need Laravel-specific metadata (e.g., Eloquent models, facades) that generic tools (PHPStan, Psalm) miss.
  • You’re building internal tooling (e.g., IDE plugins, CLI commands) that requires code analysis.
  • Performance is secondary to accuracy (Surveyor is slower than pure static analyzers but more comprehensive for Laravel).
• Look elsewhere if:
  • You need production-grade performance (e.g., real-time linting in VS Code).
  • Your stack is non-Laravel (use PHPStan/Psalm instead).
  • You only need basic syntax checks (e.g., PHP syntax validation).
  • You’re constrained by memory usage (Surveyor’s caching helps but isn’t optimized for massive codebases).

How to Pitch It (Stakeholders)

For Executives: "Surveyor is a Laravel-native static analysis tool that unlocks deep code insights—like a ‘CTRL+SHIFT+F’ for your entire application. It extracts structured metadata (e.g., method signatures, Eloquent relationships) to power tools like auto-generated docs, migration assistants, or IDE enhancements. Think of it as a ‘source of truth’ for your codebase, reducing manual effort in maintenance and tooling. Early adopters (e.g., Laravel Ranger) use it to build higher-level abstractions, and we can leverage it for [X initiative] to [specific benefit, e.g., ‘cut documentation time by 30%’ or ‘automate API client generation’]."

For Engineers: *"Surveyor gives you programmatic access to your Laravel code’s structure—classes, methods, properties, types, and even Eloquent specifics—via a clean API. Use cases:

• Build custom linters: Enforce naming conventions or detect anti-patterns.
• Generate stubs: Auto-create test classes or mocks from existing code.
• Power CLI tools: Extract usage patterns (e.g., ‘Find all classes using this deprecated facade’).
• Integrate with CI: Validate refactoring safety before merges. It’s not a replacement for PHPStan (it’s slower and less strict) but fills gaps for Laravel-specific features. Start with caching enabled (SURVEYOR_CACHE_ENABLED=true) to mitigate performance hits. Example:

$analyzer = app(\Laravel\Surveyor\Analyzer\Analyzer::class);
$methods = $analyzer->analyzeClass(User::class)->result()->publicMethods();

Contributions welcome—especially for performance optimizations!"*