sqlsrv_field_metadata — Funktion · PHP-Referenz

Signatur

sqlsrv_field_metadata(resource $stmt): array|false

Beschreibung

sqlsrv_field_metadata() gibt für jedes Feld (Spalte) eines vorbereiteten Statements ein assoziatives Array mit Metainformationen zurück. Typische Anwendungsfälle sind die dynamische Verarbeitung von Abfrageergebnissen, das automatische Mapping von Datenbankfeldern auf PHP-Strukturen oder die Validierung von Spaltentypen vor der Weiterverarbeitung.

Die Funktion benötigt ein mit sqlsrv_prepare() oder sqlsrv_query() erzeugtes Statement-Handle. Das Statement muss nicht zuvor ausgeführt worden sein – Metadaten stehen bereits nach dem Vorbereiten zur Verfügung.

Jedes Element des zurückgegebenen Arrays enthält folgende Schlüssel: Name (Spaltenname), Type (SQL-Typ als Integer), Size (Maximale Größe in Zeichen), Precision (Numerische Genauigkeit), Scale (Dezimalstellen), Nullable (ob NULL erlaubt ist) und NumericPrecision/NumericScale für numerische Typen.

Die Funktion ist besonders nützlich, wenn die Spaltenstruktur einer Abfrage zur Laufzeit nicht bekannt ist und generisch verarbeitet werden soll, beispielsweise in ORM-Schichten oder beim Generieren dynamischer Formulare aus Datenbankstrukturen.

Parameter

Name	Typ	Default	Beschreibung
$stmt Pflicht	resource		Ein gültiges Statement-Handle, das mit `sqlsrv_prepare()` oder `sqlsrv_query()` erzeugt wurde.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein numerisch indiziertes Array zurück, wobei jedes Element ein assoziatives Array mit den Metadaten einer Spalte ist. Bei einem Fehler wird false zurückgegeben. Im Fehlerfall können mit sqlsrv_errors() weitere Informationen abgerufen werden.

Beispiele

Spaltennamen und Typen einer Abfrage ausgeben

<?php
$serverName = 'localhost';
$connectionInfo = [
    'Database' => 'AdventureWorks',
    'UID'      => 'sa',
    'PWD'      => 'geheimes_passwort',
];

$conn = sqlsrv_connect($serverName, $connectionInfo);
if ($conn === false) {
    die('Verbindung fehlgeschlagen: ' . print_r(sqlsrv_errors(), true));
}

$sql  = 'SELECT ProductID, Name, ListPrice FROM Production.Product';
$stmt = sqlsrv_prepare($conn, $sql);

if ($stmt === false) {
    die('Statement-Fehler: ' . print_r(sqlsrv_errors(), true));
}

$metadata = sqlsrv_field_metadata($stmt);
if ($metadata === false) {
    die('Metadaten-Fehler: ' . print_r(sqlsrv_errors(), true));
}

foreach ($metadata as $index => $fieldMeta) {
    echo "Feld $index:\n";
    echo "  Name      : " . $fieldMeta['Name'] . "\n";
    echo "  Type      : " . $fieldMeta['Type'] . "\n";
    echo "  Size      : " . $fieldMeta['Size'] . "\n";
    echo "  Precision : " . $fieldMeta['Precision'] . "\n";
    echo "  Scale     : " . $fieldMeta['Scale'] . "\n";
    echo "  Nullable  : " . ($fieldMeta['Nullable'] ? 'Ja' : 'Nein') . "\n";
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Feld 0: Name : ProductID Type : 4 Size : 10 Precision : 10 Scale : 0 Nullable : Nein Feld 1: Name : Name Type : -9 Size : 50 Precision : 0 Scale : 0 Nullable : Nein Feld 2: Name : ListPrice Type : 3 Size : 19 Precision : 19 Scale : 4 Nullable : Nein

Dynamisches Mapping von Ergebnissen auf Basis der Metadaten

<?php
function fetchResultsWithHeaders(resource $conn, string $sql): array
{
    $stmt = sqlsrv_query($conn, $sql);
    if ($stmt === false) {
        return [];
    }

    $metadata = sqlsrv_field_metadata($stmt);
    if ($metadata === false) {
        sqlsrv_free_stmt($stmt);
        return [];
    }

    // Spaltennamen aus den Metadaten extrahieren
    $columns = array_column($metadata, 'Name');

    $result = [];
    while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_NUMERIC)) {
        $result[] = array_combine($columns, $row);
    }

    sqlsrv_free_stmt($stmt);
    return $result;
}

// Verwendung:
$rows = fetchResultsWithHeaders($conn, 'SELECT TOP 3 ProductID, Name FROM Production.Product');
foreach ($rows as $row) {
    echo $row['ProductID'] . ': ' . $row['Name'] . "\n";
}

1: Adjustable Race 2: Bearing Ball 3: BB Ball Bearing

// Wichtig · Fallstricke

Treiber-Voraussetzung: Diese Funktion ist Teil des SQLSRV-Treibers für Microsoft SQL Server und steht nur zur Verfügung, wenn die sqlsrv-Erweiterung installiert und aktiviert ist. Für Linux/macOS wird der pdo_sqlsrv-Treiber von Microsoft empfohlen.

Typkonstanten: Der Wert im Schlüssel Type entspricht ODBC-SQL-Typ-Konstanten (z. B. 4 für SQL_INTEGER, -9 für SQL_WVARCHAR). Eine vollständige Liste findet sich in der Microsoft-SQLSRV-Dokumentation.

Nullable-Werte: Der Schlüssel Nullable kann die Werte 1 (nullable), 0 (nicht nullable) oder 2 (unbekannt) enthalten.

Siehe auch

sqlsrv_prepare sqlsrv_query sqlsrv_fetch_array sqlsrv_errors sqlsrv_num_fields sqlsrv_free_stmt