Getting Started

Minimal Setup

Installation
```
composer require goaop/parser-reflection:^3.1.0
```
Add to require-dev if only needed for testing/analysis. Critical: Requires PHP 8.2+ (minimum version enforced in this release).

First Use Case Analyze a class with PHP 8+ attributes and AST-preserving features:

use GoAop\ParserReflection\ParserReflection;

$reflection = new ParserReflection();
$class = $reflection->getClass('App\Models\User');

// New: Check for PHP 8+ attributes
$attributes = $class->getAttributes();
foreach ($attributes as $attribute) {
    echo $attribute->getName(); // e.g., #[Cacheable]
}

// New: AST-preserving node resolution
$usedNodes = $class->getUsedNodes();
foreach ($usedNodes as $node) {
    if ($node->isClassReference()) {
        echo $node->getClassName(); // Resolves dynamic references
    }
}

Key Files to Explore
- src/ParserReflection.php (Core class, fully PHP 8.2+ compliant)
- src/Reflection/ClassReflection.php (Now supports getAttributes() and AST nodes)
- src/Reflection/MethodReflection.php (Updated for PHP 8.2+ and new expressions in defaults)
- src/Reflection/PropertyReflection.php (Fixed getModifiers() for PHP 8.4+)

Implementation Patterns

Common Workflows

PHP 8+ Attributes Analysis

$reflection = new ParserReflection();
$class = $reflection->getClass('App\Services\CachedService');

// Get all attributes on a class
$attributes = $class->getAttributes();
foreach ($attributes as $attribute) {
    if ($attribute->getName() === 'App\Attributes\Cacheable') {
        $args = $attribute->getArguments();
        // Process attribute arguments (e.g., cache TTL)
    }
}

// Get attributes on a method
$method = $class->getMethod('execute');
$methodAttributes = $method->getAttributes();

AST-Preserving Dependency Analysis

$reflection = new ParserReflection();
$class = $reflection->getClass('App\Services\OrderService');

// New: AST-preserving node resolution (e.g., for complex expressions)
$usedNodes = $class->getUsedNodes();
foreach ($usedNodes as $node) {
    if ($node->isClassReference()) {
        echo $node->getClassName(); // Resolves dynamic references
    }
    if ($node->isNewExpression()) {
        echo $node->getClassName(); // Supports new expressions in defaults
    }
}

Laravel Integration (PHP 8.2+)

Use in boot() for runtime analysis:

public function boot()
{
    $reflection = new ParserReflection();
    $this->analyzeServiceClasses($reflection);
}

Bind to Laravel container (PHP 8.2+):

$this->app->singleton(ParserReflection::class, function ($app) {
    return new ParserReflection($app['cache']);
});

Testing Patterns with PHP 8.2+ Features

public function testMethodCoverage()
{
    $reflection = new ParserReflection();
    $class = $reflection->getClass('App\Tests\Feature\ExampleTest');

    // Check for PHP 8.2+ attributes in tests
    $testMethods = $class->getMethods(METHOD_PUBLIC);
    foreach ($testMethods as $method) {
        $attributes = $method->getAttributes();
        if (in_array('App\Attributes\TestCase', array_column($attributes, 'name'))) {
            // Special handling for annotated tests
        }
    }
}

New: Unary Expressions Support

$property = $reflection->getClass('App\Model')->getProperty('value');
$defaultValue = $property->getDefaultValue();
if ($defaultValue->isUnaryMinus()) {
    echo 'Handles unary minus expressions (e.g., -10)';
}

Integration Tips

Caching: Cache parsed results for performance (works with PHP 8.2+):

$cache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
$reflection = new ParserReflection($cache);

Path Resolution: Override default paths (unchanged):

$reflection = new ParserReflection();
$reflection->setBasePath(base_path('custom/vendor'));

Event Listeners: Use for compile-time checks (e.g., registering event in Laravel).
PHP 8.2+ Compatibility: Leverage new features like:
- getModifiers() for properties (fixed for PHP 8.4+).
- Support for new expressions in parameter default values.
- AST-preserving node resolution for advanced analysis.

Gotchas and Tips

Pitfalls

PHP Version Requirement (BREAKING)
- Critical: This release requires PHP 8.2+. Update your environment:
```
php -v  # Must show 8.2.0 or higher
```
- If using Laravel, ensure your server and local environment meet the requirement.
File Not Found
- Ensure paths are correct; use getFileName() to debug:
```
$reflection->getClass('Class')->getFileName(); // Returns full path
```
- For Laravel, prepend app/ to class names if not autoloaded.
Attribute Resolution
- Attributes must be fully qualified (e.g., App\Attributes\Cacheable).
- Dynamic attributes (e.g., new SomeAttribute()) may not resolve correctly.
AST Node Limitations
- AST-preserving features are experimental. Use getUsedNodes() cautiously in production.
- Not all node types are supported (check isNewExpression(), isClassReference(), etc.).

Deprecated Features

Avoid deprecated nullable type declarations (fixed for PHP 8.4+):

// Avoid (deprecated in PHP 8.4+)
public function foo(?string $bar): ?string;

// Use instead
public function foo(string|null $bar): string|null;

New Expressions in Defaults

Support for new expressions in parameter defaults is new. Test thoroughly:

// Example: new \App\Models\User() in default value
$method = $reflection->getClass('App\Service')->getMethod('create');
$defaultValue = $method->getParameter('user')->getDefaultValue();
if ($defaultValue->isNewExpression()) {
    echo 'Handles new expressions in defaults';
}

Debugging

Enable Verbose Output:

$reflection = new ParserReflection();
$reflection->setVerbose(true); // Logs parsing steps

Check for Parsing Errors:

try {
    $reflection->getClass('BrokenClass');
} catch (\GoAop\ParserReflection\Exception\ParseException $e) {
    report($e); // Laravel-specific error handling
}

PHP 8.2+ Specific Issues:

If getModifiers() fails on properties, ensure your PHP version is 8.4+ or use:
```
$modifiers = $property->getModifiers() ?? 0;
```

For unary expressions, verify node types:

if (!$defaultValue->isUnaryMinus() && !$defaultValue->isUnaryPlus()) {
    // Handle other cases
}

Extension Points

Custom Reflection Classes Extend GoAop\ParserReflection\Reflection\AbstractReflection for domain-specific analysis (now supports attributes and AST nodes).
Hook into Parsing Override ParserReflection::parseFile() to preprocess files (supports PHP 8.2+ syntax and AST preservation).

Laravel Service Provider Bind the parser to the container (ensure PHP 8.2+ compatibility):

$this->app->singleton(ParserReflection::class, function ($app) {
    return new ParserReflection($app['cache']);
});

New: AST Node Extensions Extend AST node resolution for custom logic:

$nodes = $reflection->getClass('App\Service')->getUsedNodes();
foreach ($nodes as $node) {
    if ($node->isAttribute()) {
        // Custom logic for attributes
    }
    if ($node->

Parser Reflection Laravel Package