Jak korzystać z pliku .user.ini w ServBay: Lokalny przewodnik konfiguracji PHP

ServBay to zaawansowane, zintegrowane środowisko lokalne do tworzenia aplikacji webowych, zaprojektowane z myślą o programistach. Obsługuje wiele języków i stosów technologicznych, w tym elastyczne zarządzanie wersjami PHP oraz wygodne opcje konfiguracji. W praktyce różne projekty mogą mieć odmienne wymagania dotyczące ustawień PHP, takie jak limity wielkości przesyłanych plików, ograniczenia pamięci czy poziom raportowania błędów. Modyfikacja globalnego pliku php.ini wpływa na wszystkie projekty, co może być bardzo kłopotliwe przy pracy nad wieloma aplikacjami.

Na szczęście PHP oferuje mechanizm pliku .user.ini, który pozwala definiować własne ustawienia PHP tylko dla wybranego katalogu i jego podkatalogów, bez konieczności ingerencji w globalny php.ini. ServBay w pełni obsługuje pliki .user.ini, dzięki czemu dostosowanie konfiguracji PHP dla pojedynczego projektu lub folderu jest łatwe i wydajne.

W tym artykule szczegółowo omówimy sposób działania pliku .user.ini, jak z niego korzystać w ServBay oraz na praktycznych przykładach pokażemy, jak ustawić niestandardową konfigurację PHP dla określonego projektu.

Wprowadzenie do pliku .user.ini

Plik .user.ini został wprowadzony w PHP od wersji 5.3.0 jako bardziej elastyczna i bezpieczna alternatywa dla starszych sposobów ustawiania parametrów PHP w plikach konfiguracyjnych serwera WWW (np. php_value czy php_flag w .htaccess Apacza). Dzięki temu rozwiązaniu programista może umieścić w katalogu publicznym stron www plik .user.ini z własnymi dyrektywami konfiguracyjnymi, które będą dotyczyć tylko skryptów w tym katalogu oraz we wszystkich jego podkatalogach.

Najważniejsze cechy

1. Lokalny zasięg działania: Dyrektywy z pliku .user.ini działają tylko w katalogu, w którym plik się znajduje, oraz w jego podkatalogach. Nie wpływają na globalny plik php.ini ServBay ani na konfigurację innych projektów.
2. Duża elastyczność: Dla każdego projektu można zdefiniować niezależny zestaw ustawień PHP, dostosowany do jego wymagań.
3. Łatwość zarządzania: Nie trzeba zmieniać ustawień serwera ani plików konfiguracyjnych PHP na poziomie całego systemu, co zmniejsza ryzyko konfliktów i poprawia przenośność projektów.
4. Brak konieczności restartu: W przeciwieństwie do zmian w php.ini, które zwykle wymagają restartu PHP-FPM lub serwera www, zmiany w .user.ini są automatycznie wykrywane po upływie czasu określonego przez dyrektywę user_ini.cache_ttl (domyślnie 300 sekund, czyli 5 minut).

Możliwe do ustawienia dyrektywy

Nie wszystkich dyrektyw PHP można użyć w pliku .user.ini. Możliwość tę określa tzw. „tryb zmienności” (Changeable Modes) każdej dyrektywy. Tylko te, które mają tryb PHP_INI_USER, PHP_INI_PERDIR lub PHP_INI_ALL, można ustawiać w .user.ini.

Przykładowe dyrektywy, które można skonfigurować w .user.ini:

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

Dyrektywy z trybem PHP_INI_SYSTEM (np. extension_dir, zend_extension, disable_functions) nie mogą być ustawiane w .user.ini i muszą być zadeklarowane w głównym pliku php.ini lub odpowiedniej konfiguracji serwera WWW.

Aby sprawdzić dostępność poszczególnych dyrektyw, zajrzyj na oficjalną stronę PHP dotyczącą dyrektyw php.ini.

Jak używać .user.ini w ServBay

Proces korzystania z pliku .user.ini w ServBay jest bardzo prosty. Poniżej przedstawiamy szczegółowe kroki na przykładzie ustawień upload_max_filesize i memory_limit.

Załóżmy, że katalog główny Twojej strony znajduje się w domyślnej ścieżce ServBay: /Applications/ServBay/www/, a chcesz ustawić własną konfigurację PHP dla projektu o nazwie myproject, którego katalog publiczny to /Applications/ServBay/www/myproject/public.

Krok 1: Wybierz docelowy katalog

Najpierw zdecyduj, w którym katalogu chcesz zastosować lokalną konfigurację PHP. Zwykle będzie to katalog public projektu (np. w aplikacjach Laravel lub Symfony), czyli katalog obsługiwany przez serwer www, albo dowolny inny folder wymagający specjalnych ustawień.

Przykład: /Applications/ServBay/www/myproject/public

Krok 2: Utwórz lub edytuj plik .user.ini

W wybranym katalogu utwórz nowy plik o nazwie .user.ini (lub edytuj, jeśli już istnieje). Pamiętaj, że pliki zaczynające się od kropki są domyślnie ukryte w wielu systemach i menedżerach plików – być może będzie trzeba włączyć widoczność ukrytych plików.

Możesz to zrobić w terminalu:

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

Otwórz plik .user.ini w wybranym edytorze tekstu i dodaj potrzebne dyrektywy PHP, każdą w osobnej linii, np.:

; Ustawienie maksymalnej wielkości przesyłanego pliku na 20MB
upload_max_filesize = 20M

; Ustawienie limitu pamięci dla skryptów PHP na 256MB
memory_limit = 256M

; Włącz wyświetlanie błędów (zalecane tylko podczas developmentu)
display_errors = On

Zapisz i zamknij plik .user.ini.

Krok 3: Poczekaj na uaktualnienie konfiguracji lub wykonaj wymuszone odświeżenie

Zmiany w .user.ini nie działają od razu – PHP buforuje pliki konfiguracyjne dla wydajności. Domyślnie, czas ważności cache steruje dyrektywa user_ini.cache_ttl, która zwykle wynosi 300 sekund (5 minut). Po upływie tego czasu nowe ustawienia zostaną automatycznie załadowane.

Jeśli chcesz natychmiast zobaczyć efekt zmian, możesz spróbować jednej z poniższych metod (o ile ServBay i Twoja konfiguracja na to pozwalają):

1. Restartuj odpowiedni proces PHP-FPM: W oknie aplikacji ServBay znajdź wersję PHP obsługującą Twoją stronę i zrestartuj jej usługę PHP-FPM.
2. Zrestartuj ServBay: To najprostszy sposób, ale spowoduje wyłączenie wszystkich lokalnie działających usług.
3. Poczekaj na wygaśnięcie cache: W większości przypadków to rekomendowane rozwiązanie, szczególnie jeśli zmiana nie jest pilna.

Krok 4: Sprawdź, czy plik .user.ini działa

Aby potwierdzić, że Twoje ustawienia z pliku .user.ini zostały zastosowane, utwórz prosty plik PHP, który wyświetli informacje o aktualnej konfiguracji PHP.

W tym samym katalogu, w którym umieściłeś .user.ini (np. /Applications/ServBay/www/myproject/public), utwórz plik o nazwie info.php o następującej treści:

<?php
phpinfo();
?>

Zapisz plik.

Następnie otwórz w przeglądarce adres odpowiadający plikowi info.php na swoim lokalnym serwerze ServBay. Przy założeniu, że projekt korzysta z domeny myproject.servbay.demo, a plik info.php znajduje się w katalogu public, adres będzie najprawdopodobniej wyglądał tak: https://myproject.servbay.demo/info.php.

Na wyświetlonej stronie z informacjami phpinfo() odszukaj swoje ustawienia z .user.ini (np. upload_max_filesize, memory_limit, display_errors). Zobaczysz dwie kolumny: Master Value i Local Value.

• Master Value przedstawia ustawienie z globalnego pliku php.ini.
• Local Value pokazuje wartość aktualnie ustawioną dla Twojego skryptu – może ona pochodzić z pliku .user.ini lub konfiguracji serwera.

Jeśli w kolumnie Local Value widzisz wartości ustawione w .user.ini (np. 20M, 256M, On), oznacza to, że plik działa poprawnie.

Ważna uwaga: Po zakończeniu testów usuń lub ogranicz dostęp do pliku info.php, ponieważ ujawnia on szczegółowe informacje o konfiguracji Twojego serwera!

Dodatkowe wskazówki i uwagi

• Nazwa i lokalizacja pliku: Plik musi mieć dokładnie nazwę .user.ini i znajdować się w katalogu, w którym chcesz zastosować niestandardową konfigurację. Wpływa to na ten katalog i wszystkie jego podkatalogi.
• Tryb dyrektywy: Ponownie podkreślamy, że tylko wybrane dyrektywy mogą być ustawiane w .user.ini. Próba ustawienia dyrektywy w trybie PHP_INI_SYSTEM nie zadziała i zazwyczaj nie wygeneruje błędu. Sprawdź stronę PHP, aby się upewnić.
• Bufor/cache: Pamiętaj o ustawieniu user_ini.cache_ttl. Jeśli często edytujesz .user.ini i potrzebujesz natychmiastowych efektów, możesz tymczasowo zmniejszyć tę wartość w globalnym pliku php.ini (np. user_ini.cache_ttl = 5), ale nie zaleca się tego na produkcji, ponieważ może to pogorszyć wydajność. Po zmianie pliku php.ini konieczny jest restart PHP-FPM.
• Priorytet: Kolejność stosowania konfiguracji PHP to zwykle: wartości domyślne < php.ini (lub dodatkowe pliki .ini) < konfiguracja serwera WWW (php_value/php_flag, jeśli korzystasz z modułów Apache/nginx) < .user.ini < funkcja ini_set() w skrypcie. Ustawienia z .user.ini nadpisują analogiczne wartości z pliku globalnego, ale mogą być przebite przez ini_set() w kodzie PHP.
• Bezpieczeństwo: Nie przechowuj poufnych danych w plikach .user.ini. Chociaż dotyczą tylko określonego katalogu, wciąż znajdują się one w lokalizacji potencjalnie dostępnej przez Internet (choć zazwyczaj pliki ukryte są zablokowane przed dostępem).

Najczęściej zadawane pytania (FAQ)

Q: Utworzyłem plik .user.ini z ustawieniami, ale nie działa. Czemu?

A: Możliwe powody:

1. Niewłaściwa nazwa lub położenie pliku: Sprawdź, czy plik jest dokładnie nazwany .user.ini i znajduje się w odpowiednim katalogu.
2. Nieobsługiwana dyrektywa: Być może próbujesz ustawić dyrektywę, której nie można deklarować w .user.ini (nie ma trybu PHP_INI_USER lub PHP_INI_PERDIR). Sprawdź to w dokumentacji PHP.
3. Cache się nie odświeżył: Poczekaj na upływ czasu określonego przez user_ini.cache_ttl (domyślnie 5 minut), albo ręcznie zrestartuj PHP-FPM.
4. Błąd składni: Upewnij się, że w pliku .user.ini nie ma błędów.
5. Ustawienia są nadpisywane: Sprawdź, czy nie masz w kodzie wywołań funkcji ini_set(), które nadpisują konfigurację.

Q: Czym się różni plik .user.ini od globalnego php.ini?

A: Globalny plik php.ini wpływa na całe środowisko PHP (lub na wszystkie aplikacje używające konkretnej wersji PHP). Ustawienia z tego pliku obowiązują dla wszystkich skryptów PHP, chyba że zostaną nadpisane w niższym priorytecie (np. przez .user.ini lub ini_set()). Plik .user.ini działa tylko na określony katalog i jego podkatalogi oraz obsługuje jedynie wybrane dyrektywy. Jego główną zaletą jest lokalność ustawień i brak konieczności ingerowania w konfigurację ogólną.

Podsumowanie

Korzystanie z plików .user.ini w ServBay to rekomendowany sposób zarządzania konfiguracją PHP na poziomie poszczególnych projektów. Rozwiązanie to daje programiście maksymalną elastyczność i pozwala wygodnie dostosowywać środowisko PHP do specyfiki każdej aplikacji bez ryzyka wpływania na całą instalację ServBay czy inne projekty. Dzięki przedstawionym powyżej instrukcjom i przykładom, z łatwością wdrożysz własne ustawienia w swoich projektach ServBay, co przełoży się na wygodę pracy i lepszą organizację środowiska developerskiego. Ideą ServBay zawsze było zapewnienie twórcom potężnych, elastycznych narzędzi do lokalnego rozwoju, a wsparcie dla .user.ini jest doskonałym tego przykładem.