Wenn Sie Ihren PHP-Code nicht lesen können, kann das auch Ihr LLM nicht

Es gibt viele Missverständnisse, Meinungen und Influencer-Gespräche über KI. Jeder fragt: "Sind Sie bereit für KI?" - eine sehr berechtigte Frage.

KI wird nicht alles für Sie tun. Sie wird einen Versuch machen wenn Sie es zulassen, aber je nachdem, welchen Stack Sie verwenden, werden die Ergebnisse wahrscheinlich unterschiedlich ausfallen. Am wichtigsten ist es, die künstliche Intelligenz als ein zusätzliches Instrumentarium zu betrachten. Dies ist im Endeffekt nur eine weitere Möglichkeit, eine gute Auswahl an Tools wie statische Analyse, Code-Linters und gut geschriebene Tests zu nutzen.

Um Ihre Codebasis für die Verwendung von AI vorzubereiten, werden wir uns mit der Verwendung von PHPs Readalizerdenn KI-Werkzeuge sind nur so gut wie der Code, den sie lesen.

Was ist Readalizer?

Readalizer ist eine PHP-Bibliothek, die Entwicklern eine API zur Verfügung stellt, die aus einer Reihe von Regeln besteht, die sie in Ihrer Codebasis durchsetzen wird. Zur Laufzeit nimmt sie jede PHP-Datei auf, die in ihrer Konfiguration definiert ist, und tokenisiert Ihren Code unter Verwendung des Abstrakten Syntaxbaum. Ein Beispiel für eine Regel wäre NoTodoWithoutTicketRule. Zur Laufzeit, Ihr Code:

public function(stdObj $myExample) {
	// TODO add some logic
	return stdObject->valid === true; 
}

Dies wird fehlschlagen. Die Regel besagt, dass eine Art von Ticketreferenz muss innerhalb des Inline-Kommentars angegeben werden muss. Um das Problem zu beheben, müssen wir also unseren Kommentar ändern:

public function(stdObj $myExample) {
	// TODO add some logic (DEVEX-2541)
	return stdObject->valid === true; 
}

Es gibt eine Menge Regeln, so dass wir sie nicht alle durchgehen können. Was wir jedoch tun werden, ist, eine Implementierung zu zeigen und zu erläutern, warum das in einer Live-Codebasis wichtig ist.

Moment, wie unterscheidet sich das von der statischen Analyse?

Ah, ich bin froh, dass Sie das fragen. Denn im Wesentlichen ähneln ein Satz von Regeln und ein Pass-or-Fail-Tool statischen Analysatoren wie PHPStan oder PsalmPHP (beide verwenden ebenfalls den AST, um PHP-Code in Token zu zerlegen). Es gibt jedoch einen sehr deutlichen Unterschied zwischen den beiden. Die statische Analyse stellt sicher, dass Ihr Code funktioniert. Readalizer kümmert sich nicht darum, ob Ihr Code läuft oder nicht, sondern nur, dass er den Regeln folgt, die Sie ihm vorgegeben haben. Daraus können wir schließen, dass ein statischer Analyzer Teil Ihrer Codequalitäts-Toolchain ist, aber der wichtigste Anwendungsfall von Readalizer ist es, sicherzustellen, dass sowohl Menschen als auch Large Language Models Ihren Code lesen und aufgrund der von Ihnen implementierten Regelsätze bessere Entscheidungen treffen können.

Readalizer in den eigenen Worten des Autors

Etwas, das ich in meinen Artikeln gerne mache, ist die Frage an die Macher eines Projekts, wie es zustande gekommen ist und was das Ziel des Projekts ist. Ziel. Hier sind also einige Worte darüber, was Readalizer ist, in Christopher Müllerin seinen Worten:

"Readalizer wurde von Grund auf entwickelt, um sowohl Sie als auch Ihre KI-Agenten dabei zu unterstützen, Ihren PHP-Code zu verstehen. Die Inspiration für den Start dieses Pakets war ein Zitat von Ondrej Mirtes, der sagte, dass PHPStan sich nicht darum kümmert, wie Ihr Code aussieht; das ist die Aufgabe von jemand anderem. Also habe ich es zu meinem gemacht. Nachdem ich die meiste Zeit meiner Karriere damit verbracht habe, über lesbaren Code zu sprechen, dachte ich, es wäre an der Zeit, etwas dafür zu tun. Und genau da kommt Readalizer ins Spiel. Es ermöglicht Ihnen, die Regeln mit Konfigurationen, benutzerdefinierten Regeln und benutzerdefinierten Regelsätzen anzupassen, während Sie in etwa 30 Sekunden loslegen können."

Ausführen von Readalizer mit dem Vonage PHP SDK

Um zu sehen, wie das in der Praxis funktioniert, lassen wir Readalizer gegen eine reale Codebasis laufen: das PHP-SDK von Vonage.

Das Ziel ist einfach: Es soll festgestellt werden, wo die Verbesserung der Code-Konsistenz das Projekt sowohl für Menschen als auch für LLMs leichter verständlich machen kann.

Der Einstieg erfolgt in nur zwei Schritten:

composer require readalizer/readalizer

vendor/bin/readalizer --init

Dadurch erhalten Sie eine readalizer.php Konfiguration im Stammverzeichnis Ihres Projekts. Ausgezeichnet. Ich habe die Boilerplate so geändert, dass sie standardmäßig im src Verzeichnis zu suchen, und habe alle Regeln vorübergehend deaktiviert, damit wir sie einzeln aktivieren und ihre Auswirkungen sehen können.

<?php

declare(strict_types=1);

use Readalizer\Readalizer\Rules\ClassNamePascalCaseRule;

use Readalizer\Readalizer\Rules\NoStaticPropertyRule;

use Readalizer\Readalizer\Rules\RequireNamespaceRule;

use Readalizer\Readalizer\Rules\StrictTypesDeclarationRule;

use Readalizer\Readalizer\Rules\PropertyNameCamelCaseRule;

use Readalizer\Readalizer\Rules\ConstantUpperCaseRule;

use Readalizer\Readalizer\Rules\ExceptionSuffixRule;

/**

* Copy this to readalizer.php in your project root and configure your rules.

*

* Each rule is a class implementing RuleInterface (node-level) or

* FileRuleInterface (file-level). Rules can live anywhere.

*

* ── Suppressing violations ───────────────────────────────────────────────────

*

* PHP attribute on a class, method, property, or parameter:

*

*   use Readalizer\Readalizer\Attributes\Suppress;

*

*   #[Suppress]                                   // suppress ALL rules

*   #[Suppress(NoLongMethodsRule::class)]          // suppress one rule

*   #[Suppress(RuleA::class, RuleB::class)]        // suppress multiple

*

* Scope: a class-level attribute suppresses everything within the class;

* a method-level attribute suppresses everything within that method.

*

* Inline comment for line-level suppression (trailing or preceding line):

*

*   $x = something(); // @readalizer-suppress NoLongMethodsRule

*   // @readalizer-suppress                   (preceding line, suppress all)

*   // @readalizer-suppress RuleA, RuleB      (preceding line, suppress named)

*/

return [

   // Paths to scan when no paths are passed on the CLI.

   'paths' => [

       'src',

   ],

   // Memory limit for analysis (default: 2G).

   'memory_limit' => '2G',

   // Cache results between runs.

   'cache' => [

       'enabled' => true,

       'path' => '.readalizer-cache.json',

   ],

   // Optional baseline file to suppress known violations.

   // 'baseline' => '.readalizer-baseline.json',

   // Paths, directory prefixes, or glob patterns to exclude from scanning.

   'ignore' => [

       // 'rector.php',

       // 'src/',

       // '*.generated.php',

   ],

   // Choose one or more rulesets (packs).

   'ruleset' => [

       // new FileStructureRuleset(),

       // new TypeSafetyRuleset(),

       // new ClassDesignRuleset(),

       // new MethodDesignRuleset(),

       // new NamingRuleset(),

       // new ExpressionRuleset(),

   ],

   // Add or override rules on top of rulesets.

   'rules' => [

       // File structure

       // new LineLengthRule(maxLeng)th: 120),

       // new CustomFileRule(),

       // Type safety

       // new CustomTypeRule(),

       // Class design

       // new CustomClassRule(),

       // Method design

       // new CustomMethodRule(),

       // Naming conventions

       // new CustomNamingRule(),

       // Expressions & control flow

       // new CustomExpressionRule(),
   ],
];

. Als Nächstes fügte ich eine Regel nach der anderen hinzu. Als erstes fügte ich die ClassNamePascalCaseRule()hinzugefügt, die sicherstellt, dass jede Klasse in Ihrem Quellcode in PascalCase geschrieben ist (WordPress-Entwickler sollten also lieber wegschauen). Ich ließ Readalizer laufen und erhielt die Ergebnisse:

[##############################] 100% (319/319) 1s

[OK] No readability violations found.

Time: 1.06s

Keine Verstöße hier. Gute Arbeit, SDK-Autoren! Ich denke, ich wähle besser ein anderes. Also, ich habe mich für die ExceptionSuffixRule(). Diese Regel besagt, dass alle Ihre /Ausnahme's müssen identifizierbar sein müssen, indem sie Ausnahme im Klassennamen haben. Für ein LLM ist das wichtig, weil die Dateistruktur und die Namenskonventionen ihm Vorhersagbarkeit geben. Was passiert also, wenn wir dies ausführen?

[##############################] 100% (319/319) 1s

src/Client/Exception/Conflict.php

  line 7  [ExceptionSuffixRule]  Exception class "Conflict" should end with "Exception".

src/Client/Exception/Credentials.php

  line 7  [ExceptionSuffixRule]  Exception class "Credentials" should end with "Exception".

src/Client/Exception/NotFound.php

  line 7  [ExceptionSuffixRule]  Exception class "NotFound" should end with "Exception".

src/Client/Exception/Request.php

  line 10  [ExceptionSuffixRule]  Exception class "Request" should end with "Exception".

src/Client/Exception/Server.php

  line 10  [ExceptionSuffixRule]  Exception class "Server" should end with "Exception".

src/Client/Exception/Transport.php

  line 7  [ExceptionSuffixRule]  Exception class "Transport" should end with "Exception".

[FAIL] Found 6 violations.

Time: 1.10s

Aha! Jetzt kommen wir weiter. Es ist keine schlechte Entscheidung, Ausnahmen so zu schreiben - sie sind schließlich innerhalb der Namespace-Struktur als Exceptions definiert. Aber um es noch einmal zu sagen: Sie wollen, dass Ihr LLM so wenig Arbeit wie möglich hat, um die nächste Entscheidung zu treffen. Nochmals, Vorhersagbarkeit in Ihrer Codebasis ist hier der Schlüssel.

Bei nur sechs Verstößen und der Umbenennung von sechs Klassen scheint dies eine ziemlich triviale Aufgabe für Claude zu beheben. Ich öffne also meine Eingabeaufforderung in Cursorauf, füge die Verstöße ein und sage ihm, dass er sie überarbeiten soll. Ich schiebe den Code hoch, erstelle einen PR, und hey presto:

https://github.com/Vonage/vonage-php-sdk-core/pull/553

Es scheint ein kleines Beispiel zu sein, aber nur um die Vernunft zu prüfen, habe ich sogar Glean gebeten, mir in seinen eigenen Worten zu sagen, welche Verbesserungen ich an einem SDK vornehmen kann, um die Erfahrung des Agenten zu verbessern. Die Ausgabe bestätigte, was ich vermutet hatte:

• Strukturierte Argumentationsfelder hinzufügen zu Ihren API-Antworten

• Konsistente Benennungskonventionen verwenden - LLMs brauchen Vorhersehbarkeit, um Entscheidungen zu treffen

• Einfügen von Lösungsmaßnahmen in Fehlerantworten, damit Agenten wissen, wie sie Probleme beheben können

// Example: Exception naming for predictability

// BAD - LLM can't predict this is an exception

class Invalid {}

// GOOD - Clear suffix helps LLM identify exceptions

class InvalidRequestException {}

Da haben Sie es, vom Agenten selbst mit einer Ein-Satz-Eingabeaufforderung.

Schlussfolgerung

Während ein einfaches Beispiel hier dazu dient, einen sehr sanften Überblick darüber zu geben, wie man KI-fähig wird, ist es auch erwähnenswert, dass die Erfahrung des Agenten ein vielschichtiger Ansatz ist. Um mit KI erfolgreich zu sein, würde ich zum Beispiel nicht auf die vielen, vielen Influencer in den LinkedIn-Feeds hören, die sagen: "X ist schlecht, benutze Y". Das ist zu simpel. Der Ansatz von Vonage ähnelt dem anderer Branchenführer, da er plattformübergreifend angelegt ist:

• Dieser Artikel beschreibt Tools zur Verbesserung Ihrer SDKs für Agenten, die nur als LLM laufen, wie z. B. OpenClaw

• Darüber hinaus sollte ein Agent die Möglichkeit haben, einen MCP-Server als Alternative zu verwenden (Vonage hat beispielsweise unseren eigenen freigegeben), an den wiederum eine Verbindung hergestellt werden sollte:

• Ein überarbeitetes und gehärtetes Command Line Interface (CLI, und ja, Vonage hat schon seit langem eine) und eine öffentlich zugängliche Befehlsstruktur, so dass Agenten die Möglichkeit haben, die CLI selbständig zu nutzen.

Drei Ansätze, die es den KI-Werkzeugen ermöglichen, zu entscheiden, was die gestellte Aufgabe am besten erfüllt. So macht man sich KI-fähig.