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.
5. Method signatures (parameter types and return types), property types and class constant types are read from native PHP type declarations. For class types, fully-qualified class names (FQCN) are returned where possible.

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,
                    'parameters' => [
                        [
                            'name' => 'foo',
                            'type' => 'string',
                        ],
                        [
                            'name' => 'bar',
                            // FQCN for class-typed parameters
                            'type' => 'App\\SomeNamespace\\SomeDependency',
                        ],
                    ],
                    // Scalar or FQCN return type, when declared
                    'return_type' => 'App\\SomeNamespace\\ResultDto',
                ],
            ],
            'properties' => [
                [
                    'name' => 'someProperty',
                    'visibility' => 'public',
                    'declared_in' => 'App\\SomeNamespace\\SomeClass',
                    'is_static' => true,
                    // Scalar or FQCN property type, when declared
                    'type' => 'int',
                ],
            ],
            'constants' => [
                [
                    'name' => 'SOME_CONST',
                    'visibility' => 'public',
                    'declared_in' => 'App\\SomeNamespace\\SomeClass',
                    // Scalar or FQCN constant type, when declared
                    'type' => 'string',
                ],
            ],
        ],
    ],
]

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.
• Types of method parameters, return types, properties and class constants are read from native type declarations when present.
• For class-typed elements, types are normalized to fully-qualified class names (FQCN) when they can be resolved from the file namespace.
• 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.