Php Structure Discoverer Laravel Package

Product Decisions This Supports

• Dynamic Code Discovery for Plugin/Modular Architectures: Enables rapid discovery of classes, interfaces, enums, or traits across custom modules/plugins (e.g., for CMS plugins, SaaS extensibility, or marketplace integrations). Reduces manual dependency tracking and simplifies plugin compatibility checks.
• Build vs. Buy for Code Analysis Tools: Replaces custom scripts or third-party tools (e.g., PHPStan, Psalm) for lightweight, runtime-based code introspection. Ideal for internal tools where performance and flexibility outweigh static analysis.
• Performance Optimization for Large Codebases: Replaces slow get_declared_classes() or recursive glob() scans with cached, parallelized discovery. Critical for admin dashboards, IDE plugins, or CLI tools that analyze codebases on demand.
• Metadata-Driven Features:
  • Dynamic Form Generation: Auto-discover classes annotated with @Form to generate CRUD interfaces (e.g., for admin panels).
  • Policy/Authorization Rules: Scan for classes implementing Authorizable to auto-register middleware or ACL rules.
  • Event Listeners: Discover classes tagged with @ListenTo to dynamically bind event handlers (e.g., for real-time analytics).
• Testing and Migration Tools: Identify deprecated classes/interfaces during migrations or validate test coverage by scanning for unimplemented interfaces (e.g., ShouldBeTested).
• Documentation Generation: Extract class hierarchies, attributes, or inheritance chains for auto-generated API docs or architecture diagrams.

When to Consider This Package

• Avoid if:
  • You need static analysis (use PHPStan/Psalm instead). This package scans runtime files, not abstract syntax trees.
  • Your use case requires deep semantic analysis (e.g., detecting unused private methods). Tools like phpmd or pdepend are better suited.
  • You’re working in a micro-service architecture where classes are distributed across services. Discovery is limited to local filesystems.
  • Performance is critical for cold starts: First-run discovery can be slow (mitigated by caching, but not instant).
• Consider alternatives:
  • For IDE plugins: Use PHP’s built-in reflection or phpstorm-api for deeper IDE integration.
  • For dependency injection: Use Laravel’s AppServiceProvider or Symfony’s CompilerPass instead of runtime discovery.
  • For large-scale monorepos: Combine with symfony/finder or league/container for more granular control.

How to Pitch It (Stakeholders)

For Executives: *"This package lets us automate code discovery—like a GPS for our PHP codebase—so we can build features faster without manual busywork. For example:

• Plugin Marketplace: Auto-detect compatible plugins by scanning for specific interfaces (e.g., PaymentGateway).
• Admin Panel: Dynamically generate forms or menus based on annotated classes (e.g., @Configurable).
• Migration Tools: Flag deprecated code by scanning for unimplemented interfaces. It’s 10x faster than custom scripts and works out-of-the-box with Laravel’s caching. Think of it as ‘Google Search for your codebase’—but built into our stack."*

For Engineers: *"This replaces hacky glob() + class_exists() loops with a type-safe, cached, and parallelized discovery tool. Key wins:

• No more get_declared_classes() hacks: Query classes by traits, attributes, or inheritance chains (e.g., Discover::in(app_path())->withAttribute(Cacheable::class)->get()).
• Production-ready caching: Warm caches during deploy (php artisan structure-scouts:cache) for instant results.
• Extensible: Add custom conditions (e.g., ‘find classes in the App\Policies namespace’) or build your own cache drivers. Use cases:
• Dynamic middleware binding (e.g., auto-attach ThrottleRequests to rate-limited routes).
• Auto-generating API docs from @OpenApi annotations.
• Validating test coverage by scanning for unimplemented ShouldTest interfaces. Tradeoff: First run is slower, but caching makes it negligible. Perfect for tools, not runtime-critical paths."*