README

A PHP library providing AI-exposed tools for working with PHP code in the AdachSoft ecosystem.

This package exposes tools built on top of adachsoft/ai-tool-call for locating PHP classes, reading class files and inspecting PHP source code structure from files or class names.

Installation

composer require adachsoft/php-code-tools

Available tools

locate_class_file

The locate_class_file tool accepts a fully-qualified class name (FQCN) and returns the project-relative path to the file where this class is defined.

Internally it:

• uses adachsoft/static-class-finder to read Composer-generated static maps,
• applies a shared base-directory policy before resolving any path,
• normalizes the resolved file path to be relative to the configured base_path.

The tool never exposes absolute filesystem paths. Returned file_path is always relative to base_path and uses / as a directory separator.

Parameters

The tool is exposed under the name locate_class_file.

It expects a single required parameter:

• fqcn (string) – fully-qualified class name that should be resolved to a file path.

Example:

{
  "fqcn": "App\\Example\\MyService"
}

Result

On success the tool returns:

• fqcn – the same FQCN you passed as input,
• file_path – the project-relative path to the class file (relative to base_path).

Example:

{
  "fqcn": "App\\Example\\MyService",
  "file_path": "src/Example/MyService.php"
}

read_class_file

The read_class_file tool accepts a fully-qualified class name (FQCN), resolves the corresponding file path and returns the contents of that PHP file.

Internally it:

• uses the same class-location logic as locate_class_file,
• verifies the resolved file path against the configured base_path,
• reads the file contents only after the path is validated.

Parameters

The tool is exposed under the name read_class_file.

It expects a single required parameter:

• fqcn (string) – fully-qualified class name whose file contents should be read.

Example:

{
  "fqcn": "App\\Example\\MyService"
}

Result

On success the tool returns:

• fqcn – the same FQCN you passed as input,
• file_path – the project-relative path to the class file (relative to base_path),
• contents – the raw contents of the PHP file.

Example:

{
  "fqcn": "App\\Example\\MyService",
  "file_path": "src/Example/MyService.php",
  "contents": "<?php\n\ndeclare(strict_types=1);\n..."
}

inspect_php_file

The inspect_php_file tool accepts a file path relative to the configured base directory and returns structural information about the PHP file: namespace, classes, methods and properties.

Internally it:

• normalizes the user-provided relative path against base_path,
• blocks attempts to escape outside the configured base directory,
• uses adachsoft/php-code-reader to parse the PHP file and extract metadata.

Parameters

The tool is exposed under the name inspect_php_file.

It expects a single required parameter:

• file_path (string) – relative file path within the configured base directory.

Example:

{
  "file_path": "src/Example/MyService.php"
}

Result

On success the tool returns:

• file_path – the same project-relative path within base_path,
• namespace – the declared namespace of the PHP file (or null if none),
• classes – an array of class descriptors, each containing:
  • name – short class name,
  • fqcn – fully-qualified class name,
  • methods – array of method descriptors (name, visibility, declared_in),
  • properties – array of property descriptors (name, visibility, declared_in).

inspect_php_class

The inspect_php_class tool accepts a fully-qualified class name (FQCN), locates the corresponding PHP file and returns structural information about that file and its classes.

Internally it:

• resolves the class file using Composer static maps,
• verifies that the resolved path is within base_path,
• uses adachsoft/php-code-reader to extract class/namespace/method/property metadata.

Parameters

The tool is exposed under the name inspect_php_class.

It expects a single required parameter:

• fqcn (string) – fully-qualified class name to inspect.

Example:

{
  "fqcn": "App\\Example\\MyService"
}

Result

On success the tool returns:

• fqcn – the same FQCN you passed as input,
• file_path – the project-relative path to the source file (relative to base_path),
• namespace – the namespace declared in that file,
• classes – an array of class descriptors with the same structure as in inspect_php_file.

Configuration

All tools use base_path as the root directory for file access and path validation.

Example factory configuration:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

$config = new ConfigMap([
    'base_path' => '/app/project',
]);

For tools using Composer class resolution you can also provide:

• composer_dir (string|null) – optional path to the Composer metadata directory (e.g. /app/project/vendor/composer).

Path safety

This package uses adachsoft/normalized-safe-path to normalize and validate file paths against base_path.

This means:

• user-provided file paths are treated as relative to base_path,
• directory traversal attempts such as ../../etc/passwd are rejected,
• resolved class file paths are verified before they are read or returned,
• all exposed file_path values are project-relative (never absolute OS paths) and use / as a directory separator.

Preparing classes to be discoverable

The class-based tools rely on Composer autoload metadata. To make sure your classes can be located and read:

1. Configure PSR-4 autoloading in your composer.json.
2. Keep class file locations consistent with namespaces.
3. Regenerate Composer autoload files after adding or moving classes:

composer dump-autoload -o

License

This library is released under the MIT License.