adachsoft/php-code-tools

AI-exposed tools for working with PHP code (e.g. locating class files by FQCN using static Composer maps).

v0.3.0 2026-03-27 15:57 UTC

Requires

• php: >=8.3
• adachsoft/ai-tool-call: ^2.0
• adachsoft/normalized-safe-path: ^0.1
• adachsoft/php-code-reader: ^0.1.0
• adachsoft/static-class-finder: ^0.1.1
• phpstan/phpstan: ^2.1

Requires (Dev)

• adachsoft/php-code-style: ^0.4.2
• friendsofphp/php-cs-fixer: ^3.94.2
• phpunit/phpunit: ^13.0
• rector/rector: ^2.3.9

MIT

• Arkadiusz Adach

• php
• tool
• ai
• fqcn
• class-locator
• ai-tool-call
• static-class-finder

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 reading PHP source code 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 absolute 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 returning any resolved path.

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 absolute path to the class file within the configured base directory.

Example:

{
  "fqcn": "App\\Example\\MyService",
  "file_path": "/app/project/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:

• delegates file resolution to locate_class_file,
• reads the resolved file only after the path is verified against the configured base directory.

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 absolute path to the class file,
• contents - the raw contents of the PHP file.

Example:

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

read_class_code

The read_class_code tool accepts a fully-qualified class name (FQCN), reads PHP code metadata through adachsoft/php-code-reader and returns the source file contents for that class.

Internally it:

• uses adachsoft/php-code-reader to resolve the source file for the given class,
• enforces the shared base-directory policy before returning the file path and contents.

Parameters

The tool is exposed under the name read_class_code.

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 absolute path to the source file,
• contents - the raw contents of the PHP file.

read_file_code

The read_file_code tool accepts a file path relative to the configured base directory and returns the source file contents.

Internally it:

• normalizes the user-provided relative path,
• blocks attempts to escape outside the configured base directory,
• reads the resolved PHP file through adachsoft/php-code-reader.

Parameters

The tool is exposed under the name read_file_code.

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 absolute path to the resolved file,
• contents - the raw contents of the PHP file.

Configuration

All tools use base_dir as the root directory for file access.

Example factory configuration:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

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

For tools using Composer class resolution you can also provide:

• composer_dir (string|null) - optional path to the Composer metadata directory.

Path safety

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

This means:

• user-provided file paths are treated as relative to base_dir,
• directory traversal attempts such as ../../etc/passwd are rejected,
• resolved class file paths are also verified before they are returned or read.

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.