README

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

The first tool delivered by this package is locate_class_file, which resolves a PHP class file path from its FQCN using Composer's static class maps (adachsoft/static-class-finder) and exposes it through the adachsoft/ai-tool-call SPI.

Installation

composer require adachsoft/php-code-tools

Tools

locate_class_file

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

Internally it:

uses adachsoft/static-class-finder to read Composer-generated static maps without loading classes,
integrates with adachsoft/ai-tool-call so the tool can be called from AI agents and other automation.

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 (JSON-like parameters schema for ai-tool-call):

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

Result

On success the tool returns a result map with two keys:

fqcn – the same FQCN you passed as input,
file_path – the path to the file that contains the class, relative to the project root (directory with composer.json).

Example (logical shape of the result):

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

Errors

The tool can fail in two main situations:

Invalid call – the fqcn parameter is missing or is not a string. In this case the call is treated as an invalid tool invocation.
Class not found – the static Composer maps do not contain any entry for the given FQCN. In this case the tool reports a domain error that the class file cannot be found.

From the caller point of view (via adachsoft/ai-tool-call) these conditions are surfaced as standard InvalidToolCallException / ToolExecutionException errors with details about the cause.

Preparing classes to be discoverable

The tool relies entirely on Composer's static class maps. To make sure your classes can be located:

Configure PSR-4 autoloading in your project
- In your composer.json define a PSR-4 mapping for your application namespace, for example:
```
{
  "autoload": {
    "psr-4": {
      "App\\\\": "src/"
    }
  }
}
```
Place classes in directories matching their namespace
- If your FQCN is App\\Example\\MyService, the class file should be located at src/Example/MyService.php and start with:
```
<?php
     
declare(strict_types=1);
     
namespace App\Example;
     
final class MyService
{
    // ...
}
```
Regenerate Composer autoload files
- After adding or moving classes run:
```
composer dump-autoload -o
```
- This command regenerates Composer's static maps used by adachsoft/static-class-finder, so that locate_class_file can see your new classes.
Avoid classes outside Composer autoload
- Classes that are not covered by your autoload configuration (e.g. files in arbitrary directories without PSR-4 mapping) will not appear in Composer's static maps and therefore cannot be resolved by this tool.

By following the steps above you ensure that locate_class_file can reliably translate an FQCN into the corresponding file path.

License

This library is released under the MIT License.

adachsoft / php-code-tools

Maintainers

Package info

Statistics

Security