xmlrpc_server_add_introspection_data — Funktion · PHP-Referenz

Signatur

xmlrpc_server_add_introspection_data(resource $server, array $desc): int

Beschreibung

xmlrpc_server_add_introspection_data ergänzt einen mit xmlrpc_server_create erzeugten XML-RPC-Server um strukturierte Metadaten (Introspektionsdaten). Diese Daten beschreiben die verfügbaren Methoden, ihre Parameter und Rückgabetypen so, dass Clients – etwa auf Basis des XML-RPC Introspection-Standards – die API selbstbeschreibend abfragen können.

Die Beschreibungen werden als assoziatives Array übergeben und dem Server intern zugeordnet. Clients können danach per system.describeMethods eine vollständige Methodendokumentation abrufen, was die Integration und Fehlersuche erheblich erleichtert.

Typischerweise wird diese Funktion direkt nach dem Registrieren von Methoden mit xmlrpc_server_register_method aufgerufen, um jede Methode mit einer menschenlesbaren Beschreibung, Parametertypen und Rückgabetypen zu versehen.

Hinweis: Die gesamte xmlrpc_*-Erweiterung gilt als experimentell und wird in neuem Code nicht empfohlen. Für moderne Projekte sollten Bibliotheken wie phpxmlrpc oder REST-APIs bevorzugt werden.

Parameter

Name	Typ	Default	Beschreibung
$server Pflicht	resource		Eine XML-RPC-Server-Ressource, die zuvor mit `xmlrpc_server_create()` erzeugt wurde.
$desc Pflicht	array		Assoziatives Array mit den Introspektionsdaten. Typischerweise enthält es einen Schlüssel `methodList` mit Methodenbeschreibungen (Name, Zusammenfassung, Parameter, Rückgabetypen).

Rückgabewert

Typ

int

Beschreibung

Gibt 1 bei Erfolg zurück, 0 bei einem Fehler (z. B. ungültige Server-Ressource oder fehlerhaftes Datenformat).

Beispiele

Introspektionsdaten für eine einfache Methode hinzufügen

<?php
// XML-RPC-Server erstellen
$server = xmlrpc_server_create();

// Methode registrieren
xmlrpc_server_register_method($server, 'greet.hello', function($method, $params) {
    $name = $params[0] ?? 'Welt';
    return "Hallo, $name!";
});

// Introspektionsdaten definieren und hinzufügen
$desc = [
    'methodList' => [
        'greet.hello' => [
            'purpose'   => 'Gibt einen Grußtext zurück.',
            'signatures' => [
                [
                    'return' => ['type' => 'string'],
                    'params' => [
                        ['type' => 'string', 'description' => 'Name der zu grüßenden Person']
                    ]
                ]
            ]
        ]
    ]
];

$result = xmlrpc_server_add_introspection_data($server, $desc);

if ($result === 1) {
    echo "Introspektionsdaten erfolgreich hinzugefügt.\n";
} else {
    echo "Fehler beim Hinzufügen der Introspektionsdaten.\n";
}

// Server-Ressource freigeben
xmlrpc_server_destroy($server);
?>

Introspektionsdaten erfolgreich hinzugefügt.

Mehrere Methoden mit Introspektionsdaten dokumentieren

<?php
$server = xmlrpc_server_create();

// Zwei Methoden registrieren
xmlrpc_server_register_method($server, 'math.add', function($method, $params) {
    return (int)$params[0] + (int)$params[1];
});

xmlrpc_server_register_method($server, 'math.multiply', function($method, $params) {
    return (int)$params[0] * (int)$params[1];
});

// Dokumentation für beide Methoden
$desc = [
    'methodList' => [
        'math.add' => [
            'purpose' => 'Addiert zwei Ganzzahlen.',
            'signatures' => [
                [
                    'return' => ['type' => 'int'],
                    'params' => [
                        ['type' => 'int', 'description' => 'Erster Summand'],
                        ['type' => 'int', 'description' => 'Zweiter Summand'],
                    ]
                ]
            ]
        ],
        'math.multiply' => [
            'purpose' => 'Multipliziert zwei Ganzzahlen.',
            'signatures' => [
                [
                    'return' => ['type' => 'int'],
                    'params' => [
                        ['type' => 'int', 'description' => 'Erster Faktor'],
                        ['type' => 'int', 'description' => 'Zweiter Faktor'],
                    ]
                ]
            ]
        ]
    ]
];

$ok = xmlrpc_server_add_introspection_data($server, $desc);
echo $ok ? "Dokumentation registriert." : "Fehler.";

xmlrpc_server_destroy($server);
?>

Dokumentation registriert.

// Wichtig · Fallstricke

Experimentelle Erweiterung: Die xmlrpc_*-Funktionsfamilie ist seit ihrer Einführung als experimentell markiert und wurde nie als stabil klassifiziert. Das API-Verhalten sowie die unterstützten Array-Schlüssel für Introspektionsdaten sind nicht vollständig standardisiert und können sich zwischen PHP-Versionen unterscheiden.

Deprecation: In PHP 8.0 wurden alle xmlrpc_*-Funktionen als veraltet (deprecated) markiert und in PHP 8.4 vollständig entfernt. Für neue Projekte sollte auf externe Bibliotheken (z. B. phpxmlrpc) oder REST/GraphQL-APIs umgestellt werden.

Das genaue Format des $desc-Arrays ist kaum offiziell dokumentiert; die Struktur orientiert sich am internen Format der Erweiterung und kann durch Experimente oder Blick in den Quellcode ermittelt werden.

Siehe auch

xmlrpc_server_create xmlrpc_server_destroy xmlrpc_server_register_method xmlrpc_server_call_method xmlrpc_server_register_introspection_callback