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, searching, reading and inspecting PHP source code. Tools can resolve a single class to its file path, discover multiple classes through flexible search criteria, read file contents, and extract structural metadata such as namespaces, classes, methods and properties.

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"
}

find_classes

The find_classes tool searches for PHP classes using Composer-generated static maps and returns matching results with project-relative file paths.

It supports four search modes:

namespace prefix – find all classes whose namespace starts with a given prefix,
partial name – find classes whose FQCN or short name contains a given substring,
regular expression – match class names against a PCRE pattern,
name similarity – find classes whose short name is within a configurable Levenshtein distance of the query.

Like the other tools, it respects the same base_path and path-safety rules.

Parameters

The tool is exposed under the name find_classes.

Required parameters:

mode (string) – search mode, one of: namespace_prefix, partial_name, regex, similarity.
query (string) – search term: a namespace prefix, substring, PCRE pattern or name to compare, depending on the mode.

Optional parameters:

limit (integer) – maximum number of results to return (default 50, hard maximum 200). Results beyond the limit are truncated.
case_sensitivity (string) – sensitive or insensitive; applies to namespace_prefix and partial_name.
match_target (string) – fqcn or short_name; applies to partial_name, regex and similarity.
max_distance (integer) – required for similarity mode; maximum allowed Levenshtein distance.

Example:

{
  "mode": "partial_name",
  "query": "MyService",
  "match_target": "short_name",
  "limit": 10
}

Result

On success the tool returns:

mode – the search mode used,
query – the original query string,
count – number of matches in the returned list,
total – total number of matches found before truncation,
truncated – true when the result was limited by limit, otherwise false,
matches – an array of match objects, each containing:
- fqcn – fully-qualified class name,
- file_path – project-relative path to the class file (relative to base_path), or null if the file cannot be resolved.

Example:

{
  "mode": "partial_name",
  "query": "MyService",
  "count": 2,
  "total": 2,
  "truncated": false,
  "matches": [
    {
      "fqcn": "App\\Example\\MyService",
      "file_path": "src/Example/MyService.php"
    },
    {
      "fqcn": "App\\Example\\MyServiceFactory",
      "file_path": "src/Example/MyServiceFactory.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, searched and read:

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

composer dump-autoload -o

License

This library is released under the MIT License.

adachsoft / php-code-tools

Maintainers

Package info

Statistics

Security

README

Installation

Available tools

locate_class_file

Parameters

Result

find_classes

Parameters

Result

read_class_file

Parameters

Result

inspect_php_file

Parameters

Result

inspect_php_class

Parameters

Result

Configuration

Path safety

Preparing classes to be discoverable

License