Signatur
Beschreibung
Das #[Deprecated]-Attribut ist ein eingebautes PHP-Attribut (seit PHP 8.4), mit dem Entwickler Funktionen, Methoden, Klassen oder Konstanten formal als veraltet kennzeichnen können. Sobald eine so markierte Einheit aufgerufen wird, erzeugt PHP automatisch eine E_USER_DEPRECATED-Warnung – ohne dass manuell trigger_error() aufgerufen werden muss.
Der optionale Parameter $message erlaubt es, den Grund für die Abschaffung und mögliche Alternativen zu beschreiben. Dieser Text wird in die generierte Deprecation-Meldung eingebettet. Der Parameter $since gibt an, ab welcher Version die Funktionalität als veraltet gilt, und erscheint ebenfalls in der Warnmeldung.
Das Attribut ist besonders nützlich in Bibliotheken und Frameworks, wo API-Kompatibilität über mehrere Versionen hinweg wichtig ist. Es ermöglicht eine saubere, maschinenlesbare und für Entwickler transparente Kommunikation von Migrationshinweisen – direkt im Quellcode, ohne Kommentare oder externe Dokumentation.
Im Gegensatz zu einem einfachen @deprecated-PHPDoc-Kommentar wird #[Deprecated] zur Laufzeit ausgewertet und löst tatsächlich PHP-Warnungen aus, die in Fehlerprotokollen erscheinen und von Error-Handlern verarbeitet werden können.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $message | string | '' | Optionale Meldung, die den Grund für die Abschaffung sowie mögliche Ersatzfunktionen oder -methoden beschreibt. Wird in die ausgegebene Deprecation-Warnung aufgenommen. |
| $since | string | '' | Optionale Versionsangabe (z. B. '2.0'), ab der die Funktionalität als veraltet gilt. Erscheint ebenfalls in der generierten Warnmeldung. |
Beispiele
Methode als veraltet markieren
<?php
class UserManager
{
#[Deprecated(
message: 'Bitte verwende stattdessen findById()',
since: '2.1'
)]
public function getUser(int $id): array
{
return ['id' => $id, 'name' => 'Max Mustermann'];
}
public function findById(int $id): array
{
return ['id' => $id, 'name' => 'Max Mustermann'];
}
}
$manager = new UserManager();
// Löst automatisch eine E_USER_DEPRECATED-Warnung aus:
$user = $manager->getUser(42);
var_dump($user);Eigenständige Funktion als veraltet markieren
<?php
#[Deprecated(
message: 'Nutze stattdessen formatCurrency(float $amount, string $currency)',
since: '3.0'
)]
function format_money(float $betrag): string
{
return number_format($betrag, 2, ',', '.') . ' EUR';
}
function formatCurrency(float $amount, string $currency): string
{
return number_format($amount, 2, ',', '.') . ' ' . $currency;
}
// Veraltete Funktion aufrufen – löst Deprecation-Warnung aus:
echo format_money(1234.5) . PHP_EOL;
// Neue Funktion aufrufen – keine Warnung:
echo formatCurrency(1234.5, 'EUR') . PHP_EOL;Deprecation-Warnungen in Tests abfangen
<?php
#[Deprecated(message: 'Verwende newApi() statt oldApi()')]
function oldApi(): string
{
return 'veraltet';
}
// Eigenen Handler registrieren, um Deprecations gezielt zu behandeln:
set_error_handler(function (int $errno, string $errstr): bool {
if ($errno === E_USER_DEPRECATED) {
echo "[DEPRECATED erfasst]: {$errstr}" . PHP_EOL;
return true; // Standardausgabe unterdrücken
}
return false;
});
oldApi();
restore_error_handler();// Wichtig · Fallstricke
PHP-Version: #[Deprecated] steht erst ab PHP 8.4 zur Verfügung. In älteren PHP-Versionen muss weiterhin trigger_error('...', E_USER_DEPRECATED) manuell aufgerufen werden.
Kein Laufzeit-Stopp: Das Attribut verhindert die Ausführung des markierten Codes nicht – es erzeugt lediglich eine Warnung. Die Funktion oder Methode wird nach wie vor normal ausgeführt.
Kompatibilität mit PHPDoc: #[Deprecated] ersetzt nicht vollständig den @deprecated-PHPDoc-Tag, da statische Analyse-Tools (z. B. PHPStan, Psalm) weiterhin PHPDoc-Annotationen auswerten. Es empfiehlt sich, beide zu kombinieren.
Anwendbarkeit: Das Attribut kann auf Funktionen, Methoden (auch statische), Klassen-Konstanten und Eigenschaften (ab PHP 8.4 mit entsprechender Unterstützung) angewendet werden. Es kann nicht direkt auf Klassen oder Interfaces angewendet werden, um deren Instanziierung zu deprecieren – hierfür ist ein Konstruktor-Attribut nötig.