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:

PHP 8.3+ compatibility
Type safety (strict types)
PHPDoc for all public APIs
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

arielespinoza07 / php-introspector

Maintainers

Details