xattr_set — Funktion · PHP-Referenz

Signatur

xattr_set(string $filename, string $name, string $val, int $flags = 0): bool

Beschreibung

Die Funktion xattr_set() schreibt ein erweitertes Attribut (xattr) mit dem angegebenen Namen und Wert an die angegebene Datei oder das angegebene Verzeichnis. Erweiterte Attribute sind Schlüssel-Wert-Paare, die im Dateisystem direkt an Dateien geheftet werden, ohne den eigentlichen Dateiinhalt zu verändern. Sie werden unter Linux auf Dateisystemen wie ext4, XFS oder Btrfs unterstützt.

Typische Anwendungsfälle sind das Speichern von Metadaten wie MIME-Typen, Prüfsummen, Sicherheitslabels (SELinux) oder anwendungsspezifischer Informationen direkt am Dateisystem-Objekt. So lassen sich beispielsweise Thumbnails, Kommentare oder Verarbeitungsstatus an Dateien anheften, ohne eine externe Datenbank zu benötigen.

Der Parameter $flags steuert das Schreibverhalten: Ohne Flags (Standard-Wert 0) wird das Attribut angelegt oder überschrieben. Mit XATTR_CREATE schlägt das Setzen fehl, wenn das Attribut bereits existiert; mit XATTR_REPLACE schlägt es fehl, wenn es noch nicht existiert. Mit XATTR_DONTFOLLOW werden symbolische Links nicht aufgelöst, sodass das Attribut am Symlink selbst gesetzt wird.

Das PECL-Modul xattr muss installiert und das Dateisystem muss mit der Option user_xattr gemountet sein, damit erweiterte Benutzerattribute (Namespace user.*) gesetzt werden können. Andernfalls gibt die Funktion false zurück.

Parameter

Name	Typ	Default	Beschreibung
$filename Pflicht	string		Pfad zur Datei oder zum Verzeichnis, an der/dem das erweiterte Attribut gesetzt werden soll.
$name Pflicht	string		Name des erweiterten Attributs. Für Benutzerattribute ist typischerweise das Präfix `user.` voranzustellen, z. B. `user.mimetype`.
$val Pflicht	string		Wert, der dem Attribut zugewiesen werden soll. Es handelt sich um einen beliebigen Binär- oder Textstring.
$flags	int	0	Steuert das Schreibverhalten. Mögliche Werte: `XATTR_CREATE` (nur anlegen, nicht überschreiben), `XATTR_REPLACE` (nur überschreiben, nicht anlegen), `XATTR_DONTFOLLOW` (Symlinks nicht auflösen). Kombinierbar per `\|`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück. Im Fehlerfall (z. B. fehlende Berechtigung, Attribut existiert bereits bei XATTR_CREATE, kein xattr-fähiges Dateisystem) wird false zurückgegeben.

Beispiele

MIME-Typ als erweitertes Attribut an eine Datei heften

<?php
$datei = '/var/www/uploads/bild.png';

// Erweitertes Attribut setzen (anlegen oder überschreiben)
if (xattr_set($datei, 'user.mimetype', 'image/png')) {
    echo "Attribut erfolgreich gesetzt.\n";
} else {
    echo "Fehler beim Setzen des Attributs.\n";
}

// Gesetztes Attribut wieder auslesen
$wert = xattr_get($datei, 'user.mimetype');
echo "MIME-Typ: " . $wert . "\n";
?>

Attribut erfolgreich gesetzt. MIME-Typ: image/png

Attribut nur anlegen, wenn es noch nicht existiert (XATTR_CREATE)

<?php
$datei = '/tmp/testdatei.txt';
file_put_contents($datei, 'Testinhalt');

// Attribut beim ersten Mal anlegen
$ergebnis1 = xattr_set($datei, 'user.status', 'neu', XATTR_CREATE);
echo 'Erster Versuch: ' . ($ergebnis1 ? 'OK' : 'Fehler') . "\n";

// Zweiter Versuch schlägt fehl, da Attribut bereits existiert
$ergebnis2 = xattr_set($datei, 'user.status', 'verarbeitet', XATTR_CREATE);
echo 'Zweiter Versuch: ' . ($ergebnis2 ? 'OK' : 'Fehler – Attribut existiert bereits') . "\n";

// Aktuellen Wert prüfen
echo 'Wert: ' . xattr_get($datei, 'user.status') . "\n";
?>

Erster Versuch: OK Zweiter Versuch: Fehler – Attribut existiert bereits Wert: neu

// Wichtig · Fallstricke

Dateisystem-Voraussetzung: Das Dateisystem muss mit der Mount-Option user_xattr eingehangen sein (z. B. in /etc/fstab: ext4 defaults,user_xattr 0 0). Auf Dateisystemen ohne diese Unterstützung (z. B. FAT, NFS ohne xattr-Unterstützung) schlägt xattr_set() stets fehl.

Berechtigungen: Um Attribute im Namespace user.* zu setzen, benötigt der PHP-Prozess Schreibrechte auf die Datei. Attribute anderer Namespaces (z. B. security.*) erfordern in der Regel Root-Rechte.

Portabilität: Extended Attributes sind nicht auf allen Betriebssystemen identisch implementiert. Unter macOS existiert ein ähnliches Konzept, jedoch mit abweichender API. xattr_set() ist primär auf Linux ausgelegt.

Installation: Die Erweiterung ist nicht Bestandteil der PHP-Standardinstallation und muss über PECL installiert werden: pecl install xattr.

Siehe auch

xattr_get xattr_remove xattr_list xattr_supported