PHP-Klassen in Tool-Handlern

Welche Vendor- und Framework-Klassen du in eigenen Handlern nutzen darfst — und welche nicht.

In Tool-Handlern ('handler' => function (...) { ... }) hast du vollen PHP-Zugriff. Das ist mächtig — und braucht Leitplanken, damit dein Workspace nicht bricht, sobald sich die Plattform-Version ändert.

#Grundsatz

• Native PHP-Funktionen und das PHP-Standardlib sind immer erlaubt (array_*, str_*, preg_*, json_*, DateTime, DateTimeImmutable, SplStack, RecursiveDirectoryIterator usw.)
• Klassen aus der Liste unten sind freigegeben — die Plattform garantiert ihre Verfügbarkeit über Updates hinweg
• Alles andere — egal ob aus vendor/ oder dem Framework — kann jederzeit wegfallen oder sich verändern. Nutzung auf eigenes Risiko

Wenn du eine Klasse brauchst, die nicht in der Liste steht: frage den Betreiber, ob sie aufgenommen werden kann. Das hält die Plattform pflegbar.

#Freigegebene Klassen

#HTTP-Calls

Tool-Handler dürfen KEINE eigenen HTTP-Clients instanziieren — weder Cake\Http\Client, GuzzleHttp\Client noch curl_*-Funktionen. Sie sind vom Sandbox-Validator beim Sync blockiert. Der Grund: zentrale Auth-, Retry-, Timeout-, Logging- und Rate-Limit-Konfiguration über die Plattform.

Statt dessen: API-Tools verwenden. Die externe API in apis.php registrieren, das Tool referenziert sie per Name. Die Plattform baut + sendet den Request, das Handler bekommt das geparste JSON-Response zurück.

// apis.php
return [
    'apis.example' => [
        'base_url' => 'https://api.example.com',
        'headers'  => ['Authorization' => 'Bearer ...'],
    ],
];

// tools/example/getFoo.php
return [
    'tools' => [
        'getFoo' => [
            'api' => 'example',
            'endpoint' => 'foo',
            'method' => 'GET',
            'query' => ['id' => '{{args.id}}'],
            // Optional: handler nach API-Call zum Postprocessing
            'handler' => function (array $results, array $args, array $ctx): array {
                // $results enthaelt die geparste API-Antwort
                return ['summary' => $results['name'] ?? 'unknown'];
            },
        ],
    ],
];

Vollständige API-Tool-Doku: Tools über apis.php definieren.

#Zeit & Datum

#Caching

Kein Cake\Cache\Cache in Handlern (Regel 9) — der globale Cache kennt keine Workspace-Grenze. Stattdessen $ctx['cache']: tenant- und tool-gebunden, TTL max. 7 Tage, Wert max. 1 MB.

'handler' => function (array $results, array $args, array $ctx): array {
    $value = $ctx['cache']->remember('lookup_' . md5((string)$args['id']), function () use ($ctx, $args) {
        return $ctx['tool']('getFoo', ['id' => $args['id']]);
    }, 3600); // TTL in Sekunden
    // außerdem: ->get($key), ->set($key, $value, $ttlSekunden), ->delete($key)
    return ['foo' => $value];
},

#PDF-Verarbeitung

#Plattform-eigene Helfer

Abgeschlossene Liste. Nur diese Klassen sind aus Tool-Handlern nutzbar. Andere App\Tooling\*-Klassen sind Plattform-Interna, und App\Service\* ist in Tools grundsätzlich gesperrt (Regel 8 — der Code-Audit lehnt ab). Klingt ein Name plausibel (GoogleAuthService, ServiceAccountClient, OAuthHelper …), steht aber nicht hier: er existiert nicht — nimm die deklarative api-Config in apis.php (siehe 10-integrations/*.md).

Diese Klassen sind Teil der Plattform und können sich versionieren — Änderungen werden vom Betreiber kommuniziert.

#LLM aus einem Tool-Handler aufrufen

Nicht über eine Service-Klasse, sondern per Tool-Chaining über das Plattform-Tool askLlm (OpenAI/Claude/Gemini, Keys und Abrechnung laufen zentral):

'handler' => function (array $results, array $args, array $ctx): array {
    // Der Prompt kommt als Arg vom Caller — nicht im Tool-Code hart verdrahten.
    $res = $ctx['tool']('askLlm', [
        'provider' => 'claude',
        'question' => (string)$args['instruction'] . "\n\n" . (string)$args['email_text'],
    ]);
    return ['classification' => json_decode((string)($res['answer'] ?? ''), true)];
},

Parameter und Rückgabe von askLlm: listSharedTools("llm") bzw. readSharedTool("llm/askLlm.php").

#Nicht freigegeben (typische Fragen)

Wenn dein Use-Case einen dieser Bereiche braucht: das richtige Werkzeug ist meistens ein dediziertes Tool, das der Betreiber für dich baut/freigibt — nicht der direkte Klassenzugriff.

#Verboten

Diese Funktionen / Patterns dürfen in Handlern nicht verwendet werden:

• Prozesse starten: shell_exec, exec, system, passthru, proc_open, popen
• Code ausführen: eval, assert(string), create_function
• Reflection auf Plattform-Code: ReflectionClass auf Klassen unter App\…
• Unsicheres Deserialisieren: unserialize mit User-Input
• Schreiben außerhalb erlaubter Pfade: file_put_contents, fopen, mkdir etc. mit Pfaden außerhalb von tmp/ oder webroot/uploads/

Tools, die diese Muster enthalten, werden beim tm sync abgewiesen.

#Standardlib ist genug für 80% der Fälle

Bevor du nach einer Vendor-Klasse suchst: prüfe, ob die PHP-Standardlibrary reicht.

• Strings: str_replace, preg_match, mb_strtolower, sprintf
• Arrays: array_map, array_filter, array_reduce, usort
• JSON: json_encode, json_decode
• Hashing: md5, sha1, hash_hmac, password_hash
• Datums-Arithmetik: DateTimeImmutable::modify('+7 days')
• CSV: fputcsv, fgetcsv
• URLs: parse_url, http_build_query, urlencode

#Wenn du eine neue Klasse brauchst

1. Prüfe, ob sich dein Use-Case mit Standardlib oder freigegebenen Klassen lösen lässt
2. Falls nicht, frage den Betreiber: welche Klasse, welcher Zweck, welcher Tool-Kontext
3. Wird die Klasse aufgenommen, erscheint sie in dieser Liste
4. Bis dahin: das Feature kann auf Plattform-Updates fragil reagieren — nicht in produktiven Tools verwenden