Verwendung der .user.ini-Datei in ServBay: Leitfaden zur lokalen PHP-Konfiguration

ServBay ist eine leistungsstarke integrierte lokale Webentwicklungsumgebung, die speziell für Entwickler entwickelt wurde. Sie unterstützt zahlreiche Programmiersprachen und Technologien – darunter flexibles PHP-Versionen-Management und komfortable Konfigurationsoptionen. In der Praxis benötigen unterschiedliche Projekte oft jeweils eigene PHP-Einstellungen, etwa bezüglich Dateiupload-Größe, Speicherlimits oder Fehlermeldungen. Das direkte Bearbeiten der globalen php.ini würde jedoch alle Projekte betreffen, was die Verwaltung mehrerer Projekte erschwert.

Glücklicherweise bietet PHP mit der .user.ini-Datei eine Möglichkeit, individuelle PHP-Konfigurationen für bestimmte Verzeichnisse und deren Unterverzeichnisse festzulegen, ganz ohne die globale php.ini zu verändern. ServBay unterstützt .user.ini vollständig, sodass sich PHP-Einstellungen für einzelne Projekte oder Verzeichnisse bequem und effizient anpassen lassen.

In diesem Beitrag erfahren Sie, wie .user.ini funktioniert, wie Sie diese Datei in ServBay verwenden und anhand von Beispielen, wie Sie projektspezifische PHP-Konfigurationen festlegen können.

Einführung in die .user.ini-Datei

Die .user.ini-Datei wurde mit PHP 5.3.0 eingeführt. Sie stellt eine flexiblere und sicherere Alternative zur Verwendung von PHP-Konfigurationsanweisungen wie php_value oder php_flag in Webserver-Konfigurationsdateien (z. B. in Apaches .htaccess) dar. Sie erlaubt Entwicklern, eine .user.ini-Datei direkt im öffentlich erreichbaren Webverzeichnis zu platzieren – deren Anweisungen wirken dann nur für dieses Verzeichnis und dessen Unterverzeichnisse.

Hauptmerkmale

1. Lokaler Gültigkeitsbereich: Einstellungen in einer .user.ini-Datei wirken ausschließlich im entsprechenden Verzeichnis und allen dessen Unterverzeichnissen. Sie beeinflussen weder die globale ServBay-php.ini noch andere Projekte.
2. Hohe Flexibilität: Entwickler können für jedes Projekt individuell passende PHP-Konfigurationen festlegen.
3. Einfache Verwaltung: Die globale Server- oder PHP-Konfiguration muss nicht geändert werden, was das Risiko von Konflikten reduziert und die Portabilität von Projekten erhöht.
4. Kein Neustart notwendig: Änderungen an .user.ini werden nach Ablauf der durch user_ini.cache_ttl definierten Cache-Dauer automatisch übernommen (Standard: 300 Sekunden bzw. 5 Minuten) – ohne Neustart von PHP-FPM oder Webserver.

Konfigurierbare Direktiven

Nicht alle PHP-Konfigurationsanweisungen lassen sich über .user.ini festlegen. Welche Einstellungen möglich sind, regeln die sogenannten "Changeable Modes" einer Direktive. Nur Direktiven mit dem Modus PHP_INI_USER, PHP_INI_PERDIR oder PHP_INI_ALL lassen sich in .user.ini setzen.

Häufig in .user.ini genutzte Direktiven sind:

• upload_max_filesize
• post_max_size
• memory_limit
• display_errors
• log_errors
• max_execution_time
• session.save_path
• date.timezone

Direktiven mit dem Modus PHP_INI_SYSTEM (z. B. extension_dir, zend_extension, disable_functions etc.) können nicht in .user.ini gesetzt werden. Ihre Einstellung ist ausschließlich in der zentralen php.ini oder der Webserver-Konfiguration möglich.

Eine vollständige Liste mitsamt Modus finden Sie im PHP-Handbuch zur php.ini-Konfiguration.

Verwendung von .user.ini in ServBay

Die Nutzung einer .user.ini-Datei in ServBay ist einfach und selbsterklärend. Im Folgenden zeigen wir die Vorgehensweise am Beispiel der Einstellungen für upload_max_filesize und memory_limit.

Angenommen, das Wurzelverzeichnis Ihrer Webseite befindet sich im ServBay-Standardpfad /Applications/ServBay/www/. Für das Projekt myproject mit dem Web-Root /Applications/ServBay/www/myproject/public möchten Sie nun eigene PHP-Einstellungen definieren.

Schritt 1: Zielverzeichnis bestimmen

Zunächst bestimmen Sie das Verzeichnis, für das die individuellen PHP-Einstellungen gelten sollen. In der Regel ist das das öffentlich erreichbare Web-Wurzelverzeichnis Ihres Projekts (wie bei Laravel oder Symfony der public-Ordner) oder ein spezifisches Unterverzeichnis mit Sonderanforderungen.

Beispiel: /Applications/ServBay/www/myproject/public

Schritt 2: Die .user.ini-Datei erstellen oder bearbeiten

Erstellen Sie im Zielverzeichnis eine neue Datei mit dem Namen .user.ini (falls noch nicht vorhanden) bzw. editieren Sie die schon existierende Datei. Beachten Sie, dass unter vielen Betriebssystemen Dateinamen, die mit einem Punkt beginnen, standardmäßig versteckt werden. Passen Sie ggf. Ihre Einstellungen im Dateimanager an, um versteckte Dateien anzuzeigen.

Die Datei lässt sich z. B. im Terminal anlegen:

cd /Applications/ServBay/www/myproject/public
touch .user.ini

Öffnen Sie nun die .user.ini mit einem Texteditor und fügen Sie die benötigten PHP-Direktiven zeilenweise ein. Beispiel:

; Maximale Upload-Größe auf 20MB setzen
upload_max_filesize = 20M

; PHP-Speicherlimit auf 256MB setzen
memory_limit = 256M

; Fehleranzeige aktivieren (nur für Entwicklung empfohlen)
display_errors = On

Speichern und schließen Sie die .user.ini-Datei.

Schritt 3: Warten bis Einstellungen greifen oder manueller Refresh

Änderungen an .user.ini werden nicht sofort aktiv, sondern PHP puffert diese aus Performancegründen. Wie lange, regelt die Direktive user_ini.cache_ttl (Standard: 300 Sekunden = 5 Minuten). Nach Ablauf dieses Intervalls werden Änderungen automatisch übernommen.

Um Konfigurationsänderungen sofort zu testen, gibt es folgende Möglichkeiten (abhängig von Ihrer ServBay-Version und -Einstellungen):

1. PHP-FPM-Prozess neu starten: Öffnen Sie das ServBay-Interface, suchen Sie die verwendete PHP-Version und stoppen sowie starten Sie den zugehörigen PHP-FPM-Dienst neu.
2. Neustart von ServBay: Das ist der sicherste Weg, unterbricht jedoch alle lokalen Dienste.
3. Warten Sie auf das Cache-Timeout: Dies ist die empfohlene Methode, insbesondere, wenn kein akuter Handlungsbedarf besteht.

Schritt 4: Funktion der .user.ini verifizieren

Um zu prüfen, ob Ihre .user.ini wie gewünscht wirkt, legen Sie im betreffenden Verzeichnis (z. B. /Applications/ServBay/www/myproject/public) eine PHP-Datei info.php mit folgendem Inhalt an:

<?php
phpinfo();
?>

Speichern Sie die Datei info.php.

Rufen Sie dann das entsprechende info.php-Skript im Browser auf. Zum Beispiel: Sollte Ihr Projekt in ServBay unter der Domain myproject.servbay.demo erreichbar sein und die Datei im public-Verzeichnis liegen, lautet die Adresse wahrscheinlich https://myproject.servbay.demo/info.php.

Auf der phpinfo()-Seite finden Sie die aktuelle Einstellung Ihrer Direktiven – etwa upload_max_filesize, memory_limit oder display_errors. Es gibt jeweils zwei Spalten:

• Master Value: Wert aus der globalen php.ini.
• Local Value: Geltender Wert für das ausgeführte Skript, z. B. aus .user.ini oder der Webserver-Konfiguration.

Steht in Local Value Ihr neu gesetzter Wert (z. B. 20M, 256M, On), dann hat die .user.ini erfolgreich Wirkung entfaltet.

Wichtiger Hinweis: Löschen oder schützen Sie die info.php nach dem Test wieder, um sensible Serverinformationen nicht öffentlich verfügbar zu machen.

Ergänzende Hinweise und Tipps

• Dateiname und -Ort: Die Datei muss exakt .user.ini heißen und in jenem Verzeichnis liegen, für das Sie die Konfiguration ändern möchten. Ihre Wirkung erstreckt sich auch auf alle Unterverzeichnisse.
• Direktiven-Mode: Beachten Sie erneut: Nur entsprechend als PHP_INI_USER, PHP_INI_PERDIR oder PHP_INI_ALL markierte Settings dürfen in .user.ini stehen. PHP_INI_SYSTEM-Direktiven werden ignoriert und lösen in der Regel auch keine Fehlermeldungen aus. Prüfen Sie dies im PHP-Handbuch.
• Caching: Bedenken Sie das Verhalten der Einstellung user_ini.cache_ttl. Wenn Sie regelmäßig Änderungen vornehmen und schnell testen möchten, können Sie den Wert in der globalen php.ini temporär herabsetzen (z. B. user_ini.cache_ttl = 5). Für produktive Umgebungen empfehlen wir jedoch keine zu kleinen Werte, um Performanceeinbußen zu vermeiden. Eine Änderung in der globalen php.ini erfordert einen PHP-FPM-Neustart.
• Priorität: PHP-Einstellungen greifen in folgender Rangfolge: Core-Default < php.ini (bzw. geladene Zusatz-.ini) < Webserver-Konfiguration (php_value/php_flag bei Apache/nginx-Modul) < .user.ini < Funktion ini_set() in PHP-Skripten. Die Werte aus .user.ini überschreiben die entsprechenden globalen Konfigurationen, können jedoch von ini_set() innerhalb der Skripte überlagert werden.
• Sicherheit: Vermeiden Sie, vertrauliche Daten in .user.ini abzulegen. Auch wenn die Datei nur auf das aktuelle (Unter-)Verzeichnis wirkt, liegt sie im öffentlich erreichbaren Webbereich (üblicherweise sind solche Dateien aber gegen Direktzugriff geschützt).

Häufige Fragen (FAQ)

Frage: Ich habe eine .user.ini erstellt und Einstellungen eingetragen, aber sie scheinen keine Wirkung zu entfalten. Woran kann das liegen?

Antwort: Möglich wären folgende Gründe:

1. Falscher Name oder Speicherort: Vergewissern Sie sich, dass die Datei exakt .user.ini heißt und am richtigen Ort liegt.
2. Nicht unterstützter Direktiven-Modus: Vielleicht haben Sie eine Direktive gewählt, die nicht via .user.ini gesetzt werden kann (also nicht PHP_INI_USER oder PHP_INI_PERDIR). Nachzulesen im PHP-Handbuch.
3. Cache noch nicht abgelaufen: Warten Sie die durch user_ini.cache_ttl festgelegte Zeit (i. d. R. 5 Minuten) ab oder starten Sie PHP-FPM neu.
4. Syntaxfehler: Überprüfen Sie Ihre .user.ini sorgfältig.
5. Wert wird durch höhere Priorität übersteuert: Prüfen Sie, ob z. B. ein Skript via ini_set() den Wert wieder verändert.

Frage: Was ist der Unterschied zwischen einer .user.ini und der globalen php.ini?

Antwort: Die globale php.ini bestimmt die PHP-Konfiguration für die gesamte Umgebung (bzw. alle Anwendungen unter einer bestimmten PHP-Version). Sie gilt für sämtliche Skripte, es sei denn, eine lokalere Konfiguration überschreibt einzelne Werte. Die .user.ini wirkt dagegen nur im eigenen Verzeichnis und allen darin liegenden Unterverzeichnissen – und nur für entsprechend gekennzeichnete Direktiven. Der Hauptvorteil von .user.ini ist die gezielte, projektspezifische Anpassbarkeit ohne Änderungen an der globalen Infrastruktur.

Fazit

Die Verwendung der .user.ini-Datei in ServBay ist die empfohlene Methode zur Verwaltung projektspezifischer PHP-Einstellungen. Sie bietet größtmögliche Flexibilität und erlaubt es Entwicklern, die PHP-Umgebung einzelner Projekte gezielt und unabhängig von anderen Projekten oder der globalen ServBay-Konfiguration zu steuern. Dank dieses Leitfadens und der Beispiele sind Sie bestens gerüstet, .user.ini effektiv in Ihren ServBay-Projekten einzusetzen. ServBay verfolgt den Anspruch, Entwicklern ein leistungsfähiges, flexibles und einfach zu verwaltendes lokales Entwicklungswerkzeug zur Verfügung zu stellen – und die hervorragende .user.ini-Unterstützung ist ein Paradebeispiel für dieses Konzept.