Parser Laravel Package

Getting Started

• Install it as a tooling dependency, not a request-path dependency:

  composer require --dev laravie/parser
  

  If you are building a reusable Laravel package around it, require it normally instead of --dev.

• There is usually no service provider, facade, or config file to publish. Treat it as a small library you instantiate inside an Artisan command, generator, or package-discovery service.

• Look first at the package source under vendor/laravie/parser/src and its tests. Because it is a thin wrapper over nikic/php-parser, the important questions are: what node objects does it return, and which accessors are exposed in your installed version?

• Start with a single-file metadata dump in php artisan tinker or a temporary command:

  use Laravie\Parser\ClassParser;
  
  $class = (new ClassParser())->parse(app_path('Models/User.php'));
  
  dump($class);
  

  Then inspect the returned object to learn the exact accessors available in your version, for example class name, namespace, methods, properties, imports, and parameters. Do this once before building abstractions on top of it.

• First real use case: scan app/ for classes implementing an interface, extending a base class, or using a marker attribute, without autoloading every class. This is useful for package discovery, custom generators, documentation commands, and refactoring audits.

Implementation Patterns

• Parse once, cache metadata. Do not parse source files on every web request. Parse in Artisan commands, build steps, or queued jobs, and cache results keyed by file path plus filemtime() or a content hash.

  $key = 'parser:'.sha1($path.'|'.filemtime($path).'|'.config('app.version'));
  
  $metadata = Cache::rememberForever($key, fn () => $parser->parse($path));
  

• Wrap parser output in your own DTOs. Do not let raw AST nodes or package-specific node objects leak throughout your application. Normalize into small value objects such as ClassMetadata, MethodMetadata, and ParameterMetadata. That keeps upgrades manageable.

• Use it for discovery scans. Combine Laravel’s filesystem helpers with the parser:

  use Illuminate\Support\Facades\File;
  use Laravie\Parser\ClassParser;
  
  $parser = new ClassParser();
  
  $classes = collect(File::allFiles(app_path()))
      ->filter(fn ($file) => $file->getExtension() === 'php')
      ->map(fn ($file) => $parser->parse($file->getPathname()))
      ->filter()
      ->values();
  

  This pattern works well for finding job classes, event listeners, policies, console commands, or classes carrying custom attributes.

• Use it in code generation. Extract the namespace, imports, class name, and existing members from a source file, then generate a new class or modify a stub. This is safer than string-matching PHP files manually.

• Use it for documentation and audit commands. A custom php artisan app:class-audit command can list public methods missing return types, controllers with unusual method visibility, or classes that still use deprecated base classes.

• Prefer it over reflection when the class should not be loaded. Reflection requires autoloadability and can trigger side effects. This package reads source directly, which is useful for vendor files, generated code, or classes with missing runtime dependencies.

• Fall back to nikic/php-parser directly for advanced AST work. If you need custom node visitors, constant evaluation, inheritance graphs, or precise attribute argument inspection, use the underlying parser. Laravie Parser is best for the common metadata layer, not a complete static-analysis framework.

Gotchas and Tips

• This is a tooling package, not an application dependency. Do not put it in controllers, middleware, or model boot paths. Parse in commands, build scripts, queue workers, or package tooling.

• Accessor names may vary by release. Dump one parsed object before assuming a method name. A tiny throwaway command is faster than guessing from README examples.

• Imports and aliases need care. The parser can expose use statements, but resolving short class names to fully qualified names is your job. Handle aliases, grouped imports, and same-namespace references explicitly.

• Do not assume one class per file. PHP files may contain multiple classes, traits, interfaces, enums, anonymous classes, or conditional declarations. Filter node types deliberately instead of taking the first class node.

• Parser support follows the installed nikic/php-parser version. Newer PHP syntax can fail if the underlying parser is old. Keep the dependency updated and test against the PHP versions you support.

• It reads syntax, not runtime truth. Class-string constants, computed attribute arguments, inherited members, and dynamic includes are not resolved for you. If you need runtime behavior, combine parsing with reflection or Composer’s class map.

• Docblocks and native types are different. A missing native return type may still have a docblock. Decide whether your tooling trusts native types, docblocks, or both.

• Cache invalidation matters. A deploy can change many files without changing paths. Include file mtime, content hash, or application version in cache keys, and provide a command to clear parser caches.

• Watch memory on large scans. Parsing every file in a large vendor/ tree can be expensive. Chunk files, exclude irrelevant directories, and run full scans in CI or queued jobs rather than interactively.

• Extension point: if the wrapper is missing a detail, write a small adapter around nikic/php-parser node visitors and merge that output into your DTOs. Keep that adapter isolated so future package upgrades do not break your application code.