In größeren PHP-Projekten wächst die Anzahl der Klassen schnell an, und manuelles Einbinden über require oder include wird rasch unübersichtlich. Der PSR-4 Standard löst dieses Problem durch automatisches Laden von Klassen anhand ihres vollqualifizierten Namens. Dieses Tutorial erklärt, was PSR-4 ist, wie Namespaces und Verzeichnisstrukturen zusammenspielen und wie sich PSR-4 Autoloading mit Composer konfigurieren lässt. Auch ein eigener Autoloader ohne Composer wird gezeigt.
Zum Einstieg schauen wir uns an, was genau hinter dem PSR-4 Standard steckt und wie er Klassennamen auf Dateipfade abbildet.
Was ist PSR-4?
PSR steht für „PHP Standards Recommendation“ und wird von der PHP-FIG (PHP Framework Interop Group) definiert. PSR-4 beschreibt eine Konvention, wie PHP-Klassen anhand ihres vollqualifizierten Klassennamens automatisch aus dem Dateisystem geladen werden. Dabei wird ein sogenannter Namespace-Prefix einem Basisverzeichnis (Base Directory) zugeordnet. Die restliche Namespace-Struktur entspricht dann der Verzeichnisstruktur unterhalb dieses Basisverzeichnisses.
<?php
/*
* Vollqualifizierter Klassenname:
* App\Service\BenutzerService
*
* Namespace-Prefix: App\
* Base Directory: src/
* Relativer Name: Service\BenutzerService
* Dateipfad: src/Service/BenutzerService.php
*/
Der Autoloader ersetzt die Backslashes im relativen Klassennamen durch Verzeichnistrenner und hängt .php an. So entsteht der vollständige Dateipfad, unter dem die Klasse erwartet wird.
Namespaces und Verzeichnisstruktur
Die korrekte Zuordnung von Namespaces zu Verzeichnissen ist das Herzstück von PSR-4. Das folgende Diagramm veranschaulicht, wie ein vollqualifizierter Klassenname in einen Dateipfad aufgelöst wird.
flowchart TD
A["App﹨Service﹨BenutzerService"] --> B["Namespace-Prefix App﹨"]
B --> C["Base Directory src/"]
C --> D["Relativer Name<br/>Service﹨BenutzerService"]
D --> E["Dateipfad<br/>src/Service/BenutzerService.php"]
Eine typische Projektstruktur sieht folgendermaßen aus. Jede Klasse liegt in einer eigenen Datei, und der Dateiname entspricht exakt dem Klassennamen.
<?php
/*
* projekt/
* composer.json
* vendor/
* src/
* Controller/
* StartseiteController.php => App\Controller\StartseiteController
* Service/
* BenutzerService.php => App\Service\BenutzerService
* Model/
* Benutzer.php => App\Model\Benutzer
*/
Wichtig ist, dass die Groß- und Kleinschreibung der Dateinamen auf allen Betriebssystemen übereinstimmen muss. Unter Linux ist das Dateisystem case-sensitive, weshalb benutzerService.php nicht gefunden wird, wenn die Klasse BenutzerService heißt.
PSR-4 mit Composer konfigurieren
Composer unterstützt PSR-4 nativ über den autoload Eintrag in der composer.json. Dort wird der Namespace-Prefix dem Basisverzeichnis zugeordnet.
{
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
Der Namespace-Prefix muss in der composer.json mit einem doppelten Backslash enden, da JSON den einfachen Backslash als Escape-Zeichen interpretiert. Nach dem Anlegen oder Ändern der Autoload-Konfiguration muss der Befehl composer dump-autoload ausgeführt werden, damit Composer die Autoload-Dateien neu generiert. Anschließend genügt ein einzelner require Aufruf, um den Autoloader einzubinden.
<?php
require_once __DIR__ . '/vendor/autoload.php';
use App\Service\BenutzerService;
$service = new BenutzerService();
$benutzer = $service->findeAlle();
foreach ($benutzer as $name) {
echo $name . PHP_EOL;
}
Die use Anweisung importiert den vollqualifizierten Klassennamen, sodass die Klasse anschließend ohne Namespace-Prefix verwendet werden kann. Beim Erzeugen einer neuen Instanz greift der Autoloader automatisch und lädt die passende Datei.
Unterschied zwischen PSR-0 und PSR-4
Bevor PSR-4 eingeführt wurde, galt PSR-0 als Standard für Autoloading. Der wesentliche Unterschied liegt in der Behandlung des Namespace-Prefix. Bei PSR-0 wurde der gesamte vollqualifizierte Klassenname in die Verzeichnisstruktur abgebildet, was zu tief verschachtelten Ordnern führte. PSR-4 erlaubt dagegen, dass der Namespace-Prefix einem beliebigen Basisverzeichnis zugeordnet wird, ohne dass dieser Prefix selbst als Verzeichnisstruktur existieren muss. Das ermöglicht deutlich flachere Verzeichnishierarchien. PSR-0 gilt inzwischen als veraltet und wurde durch PSR-4 vollständig abgelöst.
Praxisbeispiel: Eigene Klassen autoloaden
Ein vollständiges Beispiel zeigt, wie eine eigene Klasse nach PSR-4 Konvention angelegt und verwendet wird. Die Klasse BenutzerService liegt im Verzeichnis src/Service/ und gehört zum Namespace App\Service.
<?php
/* Datei: src/Service/BenutzerService.php */
namespace App\Service;
class BenutzerService
{
public function findeAlle(): array
{
return ['Anna', 'Ben', 'Clara'];
}
public function findeNachName(string $name): ?array
{
$alle = $this->findeAlle();
$gefunden = array_filter(
$alle,
fn($eintrag) => $eintrag === $name
);
return count($gefunden) > 0 ? array_values($gefunden) : null;
}
}
Der Namespace am Anfang der Datei muss exakt zur Verzeichnisstruktur passen. Der Klassenname BenutzerService muss mit dem Dateinamen BenutzerService.php übereinstimmen. Diese beiden Regeln sind die Grundpfeiler von PSR-4.
PSR-4 ohne Composer
Auch ohne Composer lässt sich PSR-4 Autoloading umsetzen. Die Funktion spl_autoload_register() erlaubt das Registrieren eines eigenen Autoloaders, der nach PSR-4 Konvention arbeitet.
<?php
spl_autoload_register(function (string $klasse): void {
$prefix = 'App\\';
$basisVerzeichnis = __DIR__ . '/src/';
$laenge = strlen($prefix);
if (strncmp($prefix, $klasse, $laenge) !== 0) {
return;
}
$relativerKlassenname = substr($klasse, $laenge);
$datei = $basisVerzeichnis
. str_replace('\\', '/', $relativerKlassenname)
. '.php';
if (file_exists($datei)) {
require $datei;
}
});
Dieser Autoloader prüft zunächst, ob der angeforderte Klassenname mit dem konfigurierten Prefix beginnt. Falls nicht, gibt die Funktion sofort zurück, damit weitere registrierte Autoloader die Klasse laden können. Stimmt der Prefix überein, wird der relative Klassenname extrahiert, die Backslashes werden durch Schrägstriche ersetzt und der resultierende Dateipfad wird geladen. Dieser Ansatz eignet sich für kleine Projekte, in denen Composer nicht zum Einsatz kommt.
Fazit
PSR-4 ist der etablierte Standard für Autoloading in PHP und wird von nahezu allen modernen Frameworks und Bibliotheken eingesetzt. Die Zuordnung von Namespace-Prefix zu Basisverzeichnis ermöglicht eine klare und flache Projektstruktur. Composer macht die Konfiguration besonders einfach, doch auch ein eigener Autoloader mit spl_autoload_register() ist mit wenigen Zeilen umsetzbar. Entscheidend für das korrekte Funktionieren sind die Übereinstimmung von Klassennamen und Dateinamen sowie die korrekte Verzeichnisstruktur. Wer PSR-4 konsequent einsetzt, erhält ein Projekt, dessen Klassen automatisch und zuverlässig geladen werden.
