Surveyor Laravel Package

Product Decisions This Supports

• Enhanced Eloquent Query Analysis:

  • Builder Method Resolution: Fixes method resolution for Eloquent builder chains (e.g., User::where('active', true)->limit(10)), enabling tools to:
    • Generate precise query explanations (e.g., "This query filters active users and limits to 10 records").
    • Detect inefficient queries (e.g., "This where() clause could use a database index").
    • Validate query structures (e.g., "This limit() is missing an offset() for pagination").
  • Generics Propagation: Correctly propagates generic types through Eloquent builder method chains (e.g., User::whereHas('posts')->get() now accurately resolves to Collection<User>), supporting:
    • Type-safe query builders in IDEs (e.g., autocompletion for whereHas() relationships).
    • Automated test generation for Eloquent queries with nested relationships.
    • Schema validation for API responses tied to query results (e.g., "This endpoint returns User models with posts eager-loaded").

• Hardened Class and Interface Analysis:

  • Interface Support: Analyzes interfaces and their implementations (e.g., RepositoryInterface vs. UserRepository), enabling:
    • Dependency injection audits (e.g., "This class implements RepositoryInterface but lacks find()").
    • Contract validation for Laravel packages (e.g., "This service provider violates ShouldRegister interface").
  • PHP Type Keyword Resolution: Fixes method resolution for names conflicting with PHP keywords (e.g., class as a method name), improving:
    • Legacy code compatibility (e.g., parsing old Laravel versions with non-standard naming).
    • Custom trait/mixin analysis (e.g., use HasApiTokens; in Laravel Sanctum).

• Build vs. Buy for Laravel-Specific Tooling:

  • Query Optimization Tools: Strengthens the case for Surveyor over custom solutions by demonstrating ongoing fixes for Eloquent edge cases (e.g., builder method chains, generics). Reduces risk for teams evaluating the package for:
    • Query explainers (e.g., "This whereHas() query could be rewritten for performance").
    • ORM migration tools (e.g., "This has() clause is deprecated in Laravel 11").
  • Type Safety in IDEs/Plugins: Improves accuracy for tools relying on static analysis (e.g., "This variable is a Collection<User> after get()").

• Roadmap for Developer Experience (DX):

  • Eloquent Query Tooling:
    • Enable features like "Query Refactoring" (e.g., "Convert this where() chain to a query scope").
    • "Query Performance Insights" (e.g., "This join() is unnecessary—use with() instead").
  • Interface/Contract Enforcement:
    • "Missing Method Detector" (e.g., "This class implements Serializable but lacks serialize()").
  • Legacy Code Migration:
    • Identify deprecated Eloquent patterns (e.g., "This whereRaw() uses reserved keywords").

• Use Cases:

  • Database Layer Tooling: Analyze Eloquent queries to generate SQL explanations, detect N+1 queries, or validate schema constraints.
  • Testing Frameworks: Generate precise test stubs for Eloquent relationships (e.g., "This test expects a User with 3 posts").
  • Package Development: Validate that Laravel packages adhere to interfaces (e.g., ServiceProvider, Macroable).

When to Consider This Package

• Adopt if:

  • Your team relies on Eloquent query analysis (e.g., builder method chains, generics, or relationship resolution) for tools like query explainers, performance audits, or test generation.
  • You need hardened class/interface analysis (e.g., validating Laravel packages against contracts like RepositoryInterface or ShouldRegister).
  • You work with legacy Laravel code that uses non-standard naming (e.g., methods conflicting with PHP keywords) or deprecated Eloquent patterns.
  • You’re building IDE plugins or static analysis tools that require accurate type resolution for Eloquent models, collections, or builder chains.
  • You prioritize ongoing Eloquent-specific fixes (e.g., generics propagation, builder method resolution) over generic PHP parsing.
  • You need production-grade stability for Laravel-specific use cases (this release is low-risk; monitor changelogs for breaking changes).

• Look elsewhere if:

  • You need generic PHP static analysis (e.g., cross-file type inference; consider phpstan or psalm).
  • Your use case is non-Laravel (Surveyor remains Laravel/Eloquent-focused).
  • You require runtime analysis (use PHP’s reflection, xdebug, or tntsearch).
  • You’re evaluating for simple code metrics (e.g., lines of code; consider phpmetrics).
  • You need deep semantic analysis beyond Laravel’s syntax (e.g., business logic validation; consider domain-specific tools).
  • You cannot tolerate Beta-stage dependencies (though this release is stable; Surveyor is still pre-1.0).

How to Pitch It (Stakeholders)

For Executives:

*"Surveyor just got smarter about Laravel’s database layer, which unlocks new ways to automate and optimize Eloquent queries. The latest update (v0.2.4) fixes critical gaps in:

• Query Analysis: Now accurately resolves Eloquent builder chains (e.g., where()->limit()->get()) and propagates generic types (e.g., Collection<User>), enabling tools like:
  • Automated query explainers (e.g., "This whereHas() query could be rewritten for performance").
  • N+1 query detectors (e.g., "This relationship lacks with()").
• Interface Validation: Hardens class analysis to enforce Laravel contracts (e.g., "This service provider violates ShouldRegister"), reducing technical debt in packages.
• Legacy Code Support: Handles edge cases like PHP keyword conflicts (e.g., class as a method name) and deprecated Eloquent patterns. Why this matters: This release shows Surveyor is actively closing Laravel-specific gaps—not just generic PHP parsing. It’s still Beta, but the fixes (e.g., Eloquent generics, builder resolution) make it a stronger candidate for production tooling like query optimizers or IDE plugins. Think of it as Laravel’s answer to static analysis for the database layer."*

For Engineering:

*"Surveyor v0.2.4 fixes four key Eloquent and type-resolution issues:

1. Eloquent Builder Chains: Methods like where()->limit()->get() now resolve correctly, enabling accurate query analysis.
2. Generics Propagation: Collection<User> types now propagate through builder chains (e.g., User::whereHas('posts')->get()).
3. Interface Analysis: Hardened support for Laravel interfaces (e.g., RepositoryInterface), useful for package validation.
4. PHP Keyword Conflicts: Methods named after PHP keywords (e.g., class) are resolved properly. Why this matters:

• Query Tooling: Build accurate explainers, performance audits, or test generators for Eloquent queries.
• Package Development: Validate that your Laravel packages adhere to contracts (e.g., ShouldRegister).
• Legacy Code: Safely parse old Laravel versions with non-standard naming. Tradeoff: Still Beta, but these fixes show focus on Eloquent’s real-world pain points. Monitor changelogs, but this is progress toward v1.0."*

For Developers:

*"Surveyor just got better at understanding Eloquent queries and Laravel interfaces. For example:

• No more broken query analysis: Builder chains like User::where('active')->limit(10) now resolve correctly.
• Accurate generics: Collection<User> types propagate through whereHas() and other methods.
• Interface support: Detect if your class implements RepositoryInterface but lacks methods.
• Legacy code: Handles edge cases like methods named class or abstract. This means tools you build (e.g., query explainers, IDE features) will now work correctly with Eloquent. Try it if you’ve ever:
• Struggled to parse complex where()->orWhere()->with() chains.
• Needed to validate Laravel packages against interfaces.
• Worked with old Laravel code using non-standard naming. It’s still Beta, but these fixes show active improvement for Eloquent-specific use cases—not just generic PHP parsing."*