README

A small PHP library for static code reading without executing user code, without runtime reflection in the public API and without exposing the underlying AST structures.

Designed to read PHP source files from external repositories — classes do not need to be loaded by the current PHP process autoloader.

Requirements

• PHP >= 8.2
• nikic/php-parser as runtime dependency

Installation

composer require adachsoft/php-code-reader

Quick Start

use AdachSoft\PhpCodeReader\CodeReaderFactory;
use AdachSoft\PhpCodeReader\ReadOptionsDto;
use AdachSoft\PhpCodeReader\VisibilityEnum;

$factory = new CodeReaderFactory();

// Base path defines the sandbox for readable files (must be an existing, readable directory).
// Point it to the root of the external repository you want to read.
$reader = $factory->create('/path/to/external/repo/src');

// Read all classes from a file
$fileDto = $reader->readFile('Some/Subdirectory/SomeClass.php');

// Read a single class by its fully-qualified name.
// The class does NOT need to be loaded by the autoloader — the library resolves
// FQCN to file path by scanning and parsing PHP files in the base directory.
$classFileDto = $reader->readClass('App\SomeNamespace\SomeClass');

// With options: filter by visibility and include inherited members
$options = new ReadOptionsDto(
    visibilityMask: VisibilityEnum::PUBLIC->value | VisibilityEnum::PROTECTED->value,
    includeInheritance: true,
);

$classFileDto = $reader->readClass('App\SomeNamespace\SomeClass', $options);

How It Works

1. CodeReaderFactory::create($basePath) validates and resolves the base directory. All file reads are sandboxed to this path — traversal outside it is rejected.
2. readFile() parses the given PHP file using a static AST parser (nikic/php-parser) and returns a PhpFileDto with all class-like structures found in it.
3. readClass() scans all .php files under the base path, builds an in-memory FQCN → file map using AST parsing, then delegates to readFile(). No class_exists() or ReflectionClass is used at any point.
4. When includeInheritance: true is set, parent classes and used traits are also resolved from the same FQCN map, enabling full inheritance merging without autoloading.

Returned DTOs

DTO Serialization

All public DTOs expose toArray() for stable data serialization.

The serialized payload uses snake_case keys.

Example PhpFileDto::toArray() output

[
    'fqcn' => 'App\\SomeNamespace\\SomeClass',
    'file_path' => '/path/to/external/repo/src/Some/Subdirectory/SomeClass.php',
    'namespace' => 'App\\SomeNamespace',
    'classes' => [
        [
            'name' => 'SomeClass',
            'fqcn' => 'App\\SomeNamespace\\SomeClass',
            'file_path' => '/path/to/external/repo/src/Some/Subdirectory/SomeClass.php',
            'methods' => [
                [
                    'name' => 'someMethod',
                    'visibility' => 'public',
                    'declared_in' => 'App\\SomeNamespace\\SomeClass',
                    'is_static' => false,
                ],
            ],
            'properties' => [
                [
                    'name' => 'someProperty',
                    'visibility' => 'public',
                    'declared_in' => 'App\\SomeNamespace\\SomeClass',
                    'is_static' => true,
                ],
            ],
        ],
    ],
]

Notes

• readClass() accepts a plain string FQCN (without leading backslash). The class does not need to exist in the current PHP process.
• readFile() and readClass() both return properties and methods.
• Static metadata is included for both methods and properties.
• The public API never returns AST nodes.
• CodeReader instances must be created via CodeReaderFactory::create().
• File security: symlinks and path traversal sequences that resolve outside the configured base path are rejected.