README

A modern, type-safe PHP reflection library that extracts comprehensive metadata from classes, including properties, methods, constants, DocBlocks, and more.

Features

• 🔍 Complete Class Metadata - Extract all information about classes, interfaces, traits, and enums
• 📍 Member Source Tracking - Know exactly where each member comes from (trait, parent, interface, or self)
• 📝 Rich DocBlock Parsing - Full support for @param, @return, @var, @throws, and custom tags
• 🎯 Type Resolution - Handles union types, intersection types, and special types (self, parent, static)
• 🏷️ Attributes Support - PHP 8+ attributes with arguments
• 🔒 Visibility & Modifiers - Track public/protected/private, static, readonly, final, abstract
• 💾 Optional Caching - Built-in PSR-16 compatible caching layer
• 🎨 Value Objects - Immutable, type-safe metadata structures
• 🔧 PHP 8.3+ Ready - Leverages modern PHP features

Installation

composer require arielespinoza07/php-introspector

Quick Start

use Introspector\Reader;

$reader = new Reader();
$metadata = $reader->read(MyClass::class);

// Access class information
echo $metadata->class->name;
echo $metadata->class->type->value;
echo $metadata->class->modifier->isFinal;

// Access properties with source tracking
foreach ($metadata->properties as $property) {
    echo $property->name;
    echo $property->type?->name;
    echo $property->declaringSource->type->value; // "self", "trait", "parent", "interface"
}

// Access methods
foreach ($metadata->methods as $method) {
    echo $method->name;
    echo $method->returnType?->name;
    echo $method->docBlock?->summary;
}

// Access constants
foreach ($metadata->constants as $constant) {
    echo $constant->name;
    echo $constant->value;
    echo $constant->visibility->value;
}

Documentation

Getting Started

• Installation - Requirements and setup
• Core Concepts - Understanding the metadata structure

Key Features

• Member Source Tracking ⭐ NEW - Track where members originate
• DocBlocks - Parse and access DocBlock information
• Type System - Work with PHP types (union, intersection, nullable, generics)
• Attributes - PHP 8+ attributes support
• Constants - Class constants with visibility and types

Advanced Topics

• Traits and Inheritance - Working with traits and class hierarchies
• Caching - Performance optimization with caching
• JSON Output - Export metadata as JSON
• Best Practices - Performance tips and patterns

Member Source Tracking

NEW FEATURE - Track the origin of every class member:

use Introspector\Enums\SourceType;

foreach ($metadata->properties as $property) {
    match ($property->declaringSource->type) {
        SourceType::Self_ => echo "{$property->name} declared in this class",
        SourceType::Trait_ => echo "{$property->name} from {$property->declaringSource->shortName} trait",
        SourceType::Parent_ => echo "{$property->name} inherited from parent",
        SourceType::Interface_ => echo "{$property->name} from interface",
    };
}

Learn more about Member Source Tracking →

Performance

PHP Introspector is designed for production use with built-in caching:

use Introspector\Cache\CachedReader;
use Introspector\Cache\ArrayCache;

$cache = new ArrayCache();
$cachedReader = new CachedReader(new Reader(), $cache);

// First call: ~5-15ms
$metadata = $cachedReader->read(User::class);

// Subsequent calls: ~0.05-0.1ms (100x faster!)
$metadata = $cachedReader->read(User::class);

Learn more about Caching →

Real-World Example

trait TimestampTrait
{
    private ?DateTimeImmutable $createdAt = null;
    public function touch(): void { /* ... */ }
}

interface Jsonable
{
    public function toJson(): string;
}

class User implements Jsonable
{
    use TimestampTrait;

    private string $name;
    public function toJson(): string { /* ... */ }
}

$reader = new Reader();
$metadata = $reader->read(User::class);

foreach ($metadata->properties as $property) {
    echo "{$property->name}: {$property->declaringSource->type->value}\n";
}
// Output:
// createdAt: trait (from TimestampTrait)
// name: self

foreach ($metadata->methods as $method) {
    echo "{$method->name}: {$method->declaringSource->type->value}\n";
}
// Output:
// touch: trait (from TimestampTrait)
// toJson: interface (from Jsonable)

Requirements

• PHP 8.3 or higher

Testing

The library includes comprehensive test fixtures demonstrating all features:

composer test

Contributing

Contributions are welcome! Please ensure:

1. PHP 8.3+ compatibility
2. Type safety (strict types)
3. PHPDoc for all public APIs
4. Tests for new features

License

MIT License. See LICENSE for details.

Credits

Built with ❤️ by Ariel Espinoza.

Need help? Open an issue | Read the docs