Classtools Laravel Package

Product Decisions This Supports

• Codebase Introspection & Tooling:

  • Enable self-service discovery of classes/interfaces/traits for internal tools (e.g., auto-generating API documentation, dependency graphs, or migration scripts).
  • Replace manual processes: Eliminate ad-hoc grep/find commands or IDE-based searches for metadata (e.g., "Find all classes using HasFactory").
  • Power Laravel-specific tools:
    • Dynamic Service Providers: Auto-register discovered classes (e.g., all ServiceContract implementations).
    • Event Listeners: Generate event handlers from annotated classes (e.g., @ListenTo('order.created')).
    • Test Data Factories: Seed databases from class annotations (e.g., @Fixture traits).

• Build vs. Buy:

  • Buy: Avoid reinventing class discovery logic (e.g., replacing custom glob() + ReflectionClass scripts).
  • Extend: Use as a foundation for custom code generators (e.g., GraphQL schemas from classes, OpenAPI specs, or admin panel CRUD).
  • Complement: Pair with Laravel’s built-in tools (e.g., php artisan make:controller) to add intelligence (e.g., "Generate a controller for all Resource classes").

• Roadmap Priorities:

  • Monorepo/Modular Apps: Standardize class discovery across microservices or Laravel packages (e.g., shared App\Contracts).
  • Migration Automation: Identify breaking changes during PHP/Laravel upgrades (e.g., deprecated methods, removed traits).
  • Plugin Ecosystem: Enable third-party packages to discover and validate classes in user codebases (e.g., "This package requires classes implementing CacheableInterface").

• Use Cases:

  • Dynamic Configuration: Generate config/services.php entries for all discovered service classes.
  • Security Audits: Flag classes with unsafe methods (e.g., exec(), file_get_contents()) via reflection.
  • Performance: Identify unused classes for dead-code elimination (e.g., not()->where('isUsedInTests')).
  • Documentation: Auto-generate API docs from PHPDoc blocks in classes/interfaces.

When to Consider This Package

• Adopt If:

  • Your team frequently analyzes or transforms class structures (e.g., for scaffolding, audits, or meta-programming).
  • You need programmatic access to class metadata (e.g., namespaces, traits, interfaces) without manual traversal.
  • You’re building Laravel tooling that requires class discovery (e.g., custom Artisan commands, IDE plugins, or dev tools).
  • You want to reduce boilerplate (e.g., auto-generating service bindings, event listeners, or test factories).
  • Your codebase is modular or monolithic with shared libraries needing analysis (e.g., plugins, themes, or microservices).

• Look Elsewhere If:

  • You only need basic class autoloading (use Laravel’s ClassLoader or app()->make()).
  • Your use case is runtime-focused (e.g., dynamic instantiation) rather than filesystem-based (e.g., php artisan tasks).
  • You require advanced AST manipulation (e.g., modifying class bodies; use nikic/PHP-Parser).
  • Your project is Windows-heavy: Path handling assumes Unix-like systems (test thoroughly).
  • You need deep Laravel integration (e.g., resolving bound classes in the container; this package is PHP-agnostic).
  • Performance is critical: Reflection and file scanning add overhead; benchmark for large codebases (>10K classes).

How to Pitch It (Stakeholders)

For Executives:

*"This package automates manual codebase tasks, saving dev time and reducing errors. For example:

• Cut release cycles by auto-generating API clients or service providers from discovered classes (e.g., save 10+ hours per major release).
• Improve code quality by identifying unused classes or security risks (e.g., flagging classes with exec() calls).
• Future-proof plugins/microservices by standardizing how we analyze shared libraries across teams. It’s a low-cost, high-impact tool—like grep for PHP classes, but programmable. Let’s pilot it for [specific use case, e.g., ‘auto-generating admin panels’] in the next sprint."*

For Engineers:

*"ClassTools lets you query your codebase like a database:

• Find classes by traits/interfaces: iter->type('App\Contracts\Cacheable')->where('isInstantiable').
• Generate code dynamically: Transform classes into a single file (e.g., for docs) or wrap them in namespaces.
• Build Laravel tooling: Pair with ReflectionClass to create custom Artisan commands, IDE helpers, or dev tools. Why use it?
• No more manual searches: Replace grep -r 'class ' with programmatic discovery.
• Chainable filters: Works like Laravel collections (type()->inNamespace()->not()).
• Lightweight: Just 130 stars but packed with functionality—no bloat. Example win: If we’re building a ‘Code Health’ dashboard, this could power the ‘Unused Classes’ or ‘Security Risks’ sections in minutes."*

For Architects/Tech Leads:

*"This fills a gap in Laravel’s tooling:

• Complements existing tools: Works with Composer, Symfony Finder (used in Laravel), and PHP’s SPL.
• Extensible: Add custom filters/transformers for niche use cases (e.g., ‘find classes with @Deprecated’).
• Risk-mitigated: WTFPL license is permissive, but we can isolate usage (e.g., Artisan commands) to avoid core conflicts. Key ask: Let’s validate it for [use case, e.g., ‘auto-generating API docs’] and decide if it belongs in our internal toolkit or open-source ecosystem."*

Call to Action: "Propose a 2-week pilot to build [specific tool, e.g., a ‘Class Auditor’ Artisan command]. If it saves 5+ hours/month, we’ll expand its use."