Php Token Analyzer Laravel Package

Getting Started

Install the package with composer require imanghafoori/token-analyzer. Start by analyzing a simple PHP file using TokenAnalyzer::analyzeFile($path), which returns structured information about functions, classes, traits, namespaces, and use statements — all extracted from tokens without runtime execution. For example:

$analyzer = new \Imanghafoori\TokenAnalyzer\TokenAnalyzer();
$tokens = $analyzer->analyzeFile('app/Services/MyService.php');
// $tokens contains parsed metadata like classes, methods, docblocks, etc.

This is ideal for static code analysis tasks like validating conventions, generating documentation scaffolds, or enforcing internal project standards — without bootstrapping a full framework.

Implementation Patterns

• Static Analysis Pipelines: Integrate into custom linters, CI checks (e.g., via GitHub Actions), or IDE plugins to detect violations (e.g., missing @method annotations, forbidden function calls, or incorrect return types).
• Code Generation Tools: Use parsed method signatures and docblocks to scaffold templates, test stubs, or DTOs (e.g., from @property annotations).
• Refactoring Validation: Before/after refactorings, compare token structures to ensure behavioral consistency (e.g., verify method visibility wasn’t unintentionally changed).
• Framework-Agnostic Utilities: Since it's decoupled from Laravel, use it in standalone tools — e.g., a php-analyzer CLI that scans codebases for deprecated constructs across multiple projects.

Gotchas and Tips

• Token Parsing vs. Full Parsing: It uses PHP’s token_get_all() under the hood, so complex edge cases (e.g., nested heredoc/nowdoc, PHP 8.1+ named arguments, or polyfill quirks) may behave differently than PHP’s internal engine. Always validate against your target PHP version.
• DocBlock Interpretation: Relies on phpdocumentor/reflection-docblock; ensure compatible versions are installed (it supports both v4 and v5), and test with complex PHPDoc patterns (e.g., generics, union types in @param).
• Performance: For large projects, avoid scanning files repeatedly — cache analysis results per file hash (e.g., using Symfony’s Filesystem component + cache adapters).
• Extension Points: While the package is minimal, you can extend behavior by subclassing or hooking into its low-level TokenStream processing. Check src/Analyzers/ for hooks into method/class traversal logic.
• Missing Dependencies Warning: If phpdocumentor/reflection-docblock conflicts (e.g., with newer PHPStan or Psalm deps), use --with-all-dependencies during install or pin to ^4.1 or ^5.3 explicitly.