Surveyor Laravel Package

Product Decisions This Supports

• Codebase Introspection & Tooling Ecosystem: Enables building internal developer tools (e.g., IDE plugins, documentation generators, or custom linters) by exposing structured metadata about Laravel applications. Example: A "Laravel Code Health Dashboard" that visualizes class dependencies, method complexity, or usage patterns.
• Build vs. Buy for Static Analysis: Justifies not reinventing wheel for parsing PHP/Laravel code (e.g., avoids manual AST traversal or regex-based solutions). Reduces technical debt for teams needing deep code insights.
• Roadmap for Developer Experience (DX): Supports initiatives like:
  • Automated Documentation: Extract class/method metadata to auto-generate API docs (e.g., Swagger/OpenAPI).
  • Custom Linters: Build rules for Laravel-specific best practices (e.g., "avoid business logic in controllers").
  • Migration Tools: Analyze codebases pre/post major Laravel version upgrades (e.g., "which classes use deprecated Route::controller?").
• Use Cases:
  • Onboarding: Accelerate new dev ramp-up by surfacing codebase structure (e.g., "here are all the services that interact with the User model").
  • Refactoring: Identify safe-to-modify components via dependency graphs or unused methods.
  • Security Audits: Flag hardcoded secrets or sensitive method names (e.g., decrypt() calls).

When to Consider This Package

• Adopt if:
  • Your team needs structured PHP/Laravel metadata for internal tools (not just runtime reflection).
  • You’re building custom static analysis (e.g., linters, IDE features) and want to avoid parsing PHP manually.
  • You’re part of a large Laravel codebase (>50K LOC) where understanding dependencies is critical.
  • You’re integrating with Laravel Ranger (for high-level DTOs) or other Laravel tooling.
• Look elsewhere if:
  • You need runtime analysis (use PHP’s built-in reflection or phpstan).
  • Your use case is simple (e.g., basic code metrics; consider phpmetrics or phploc).
  • You require deep semantic analysis (e.g., type inference across files; consider phpstan or psalm).
  • Your codebase is non-Laravel PHP (Surveyor is Laravel-specific).
  • You need production-grade stability (package is in Beta; API may change pre-v1.0).

How to Pitch It (Stakeholders)

For Executives:

"Surveyor is a Laravel-native static analysis tool that turns our codebase into structured data—like a ‘Google Maps for our PHP classes.’ This lets us build custom tools (e.g., auto-generated docs, smarter IDE features) without reinventing the wheel. For example, we could automatically flag technical debt or accelerate onboarding by surfacing class dependencies. It’s a low-risk investment (Beta but actively maintained) that unlocks high-value internal tooling—think of it as ‘GitHub Copilot for our codebase.’"

For Engineering:

*"Surveyor gives us programmatic access to parsed metadata about our Laravel app: classes, methods, properties, return types, and more. This is a game-changer for:

• Building custom linters (e.g., ‘no SQL in controllers’).
• Generating docs (e.g., auto-extracting method signatures for Swagger).
• Refactoring safely (e.g., ‘what breaks if I rename this service?’). It’s not a replacement for PHPStan (which does runtime analysis), but it’s the missing link for static, structured code introspection. The tradeoff? It’s Beta, but the API is designed to evolve intentionally—we’d need to monitor changelogs but avoid major rework."*

For Developers:

*"Imagine if your IDE could instantly tell you:

• ‘This controller uses 3 services; here’s their hierarchy.’
• ‘This method has no tests; here’s why.’
• ‘This trait is only used in one place—safe to modify.’ Surveyor lets us build these features by exposing raw code structure as data. No more scraping HTML docs or guessing—just structured PHP objects we can query. It’s like grep for your codebase, but smarter."*