Przewodnik konfiguracji PHP w ServBay: dostosowywanie php.ini, PHP-FPM i modułów rozszerzeń

ServBay oferuje programistom webowym potężne i elastyczne lokalne środowisko PHP. Aby sprostać wymaganiom różnych projektów, możesz chcieć zmienić rozmaite ustawienia PHP, takie jak limit pamięci, maksymalny rozmiar plików do uploadu, poziom raportowania błędów lub aktywować wybrane rozszerzenia.

Ten artykuł szczegółowo wyjaśnia, jak zmieniać konfigurację PHP w ServBay. ServBay zaleca oraz udostępnia wygodny graficzny interfejs użytkownika (UI) do zarządzania tymi ustawieniami. Choć wiedza o lokalizacji i strukturze plików konfiguracyjnych (takich jak php.ini i php-fpm.conf) może być pomocna, zdecydowanie zaleca się dokonywanie wszelkich zmian za pośrednictwem interfejsu ServBay, aby zapewnić trwałość i kompatybilność konfiguracji.

Ważna uwaga

Prosimy nie edytować ręcznie plików konfiguracyjnych PHP generowanych przez ServBay (znajdujących się w /Applications/ServBay/etc/php/<version>/ i podkatalogach). Te pliki są zarządzane przez ServBay, a wszelkie ręczne zmiany zostaną nadpisane podczas aktualizacji, restartu bądź innych operacji. Wszelkie zmiany należy wprowadzać wyłącznie poprzez interfejs użytkownika ServBay.

Przegląd

W ServBay pliki konfiguracyjne różnych wersji PHP przechowywane są w osobnych katalogach. Na przykład, główny plik konfiguracyjny PHP 8.3 znajduje się w katalogu /Applications/ServBay/etc/php/8.3.

Najważniejsze pliki konfiguracyjne to:

• php.ini: Główny plik konfiguracyjny PHP, mający wpływ zarówno na CLI, jak i środowisko webowe.
• php-fpm.conf: Konfiguracja PHP-FPM (FastCGI Process Manager), głównie oddziałuje na działanie i wydajność PHP „za” serwerem (np. Caddy lub Nginx).
• conf.d/: Katalog z plikami konfiguracyjnymi (.ini) do ładowania poszczególnych rozszerzeń PHP, np. xdebug.ini, opcache.ini itd.

Choć pliki te istnieją, ServBay oferuje bezpieczniejszy i wygodniejszy sposób ich modyfikacji.

Konfiguracja poprzez interfejs użytkownika ServBay (zalecana metoda)

ServBay udostępnia intuicyjny interfejs graficzny, który umożliwia bezpośrednią zmianę różnych parametrów PHP. Po dokonaniu zmian w UI i ich zapisaniu, ServBay automatycznie zastosuje zmiany i – jeśli będzie to konieczne (zazwyczaj automatycznie) – zrestartuje odpowiednią usługę PHP, bez potrzeby edytowania plików lub używania linii komend.

Aby uzyskać dostęp do konfiguracji PHP:

1. Otwórz główne okno ServBay.
2. W lewym pasku nawigacji kliknij Języki.
3. Na liście dostępnych języków znajdź i wybierz wersję PHP, którą chcesz konfigurować (np. kliknij PHP 8.3).
4. Po prawej stronie zobaczysz szczegółowe informacje oraz opcje konfiguracji wybranej wersji PHP.

Przykładowy interfejs konfiguracji PHP wygląda następująco:

Zazwyczaj interfejs dzieli się na trzy główne sekcje: konfiguracja PHP-FPM, PHP (php.ini) oraz modułów rozszerzeń. Omawiamy je poniżej.

Konfiguracja PHP FPM

Wskazówka

Ustawienia w php-fpm.conf głównie wpływają na zachowanie PHP w środowisku serwera webowego. Zmiany dokonane za pomocą interfejsu ServBay w tej sekcji będą nadpisywać (przysłaniać) odpowiednie ustawienia z php.ini, lecz będą dotyczyć jedynie zapytań z weba. Te ustawienia nie mają wpływu na uruchamianie PHP z poziomu konsoli (CLI).

Usługi webowe ServBay (Caddy lub Nginx) komunikują się z PHP właśnie przy użyciu PHP-FPM. Interfejs konfiguracji PHP-FPM pozwala dostosować parametry istotne dla wydajności i stabilności PHP w środowisku webowym, na przykład:

• Zarządzanie procesami (pm): Określa sposób uruchamiania i obsługi procesów PHP-FPM (dynamic, static itd.).
• Liczba procesów (pm.max_children, pm.start_servers, itd.): Określa maksymalną liczbę procesów potomnych, liczbę procesów startowych i inne, wpływając na obsługę współbieżności.
• Limit pamięci (memory_limit): Ustawienie w tym miejscu będzie nadrzędne wobec wartości z php.ini i dotyczy tylko zapytań webowych.
• Logi błędów i wyświetlanie błędów: Możliwość określenia ścieżek logów błędów, poziomu raportowania i wyświetlania błędów w przeglądarce.

Na przykład, aby zwiększyć limit pamięci PHP w środowisku webowym z wartości domyślnej (np. 64M lub 128M) do 1G, wystarczy w sekcji konfiguracji PHP-FPM interfejsu ServBay znaleźć opcję memory_limit, wybrać 1G z rozwijanego menu i zapisać zmiany. Ta zmiana dotyczy tylko uruchamianych przez serwer webowy skryptów, natomiast skrypty PHP uruchamiane z konsoli będą nadal korzystać z ustawień memory_limit zdefiniowanych w php.ini.

Przykład: Jeśli w php.ini memory_limit = 512M, a w konfiguracji PHP-FPM memory_limit = 128M:

• Skrypt uruchamiany w CLI będzie mieć limit pamięci 512M.
• Skrypt dostępny przez web – 128M.

Konfiguracja php.ini

Wskazówka

Ustawienia z php.ini są globalne – obowiązują zarówno w CLI, jak i w webowej wersji PHP. Jednak, jak wspomniano, ustawienia o tej samej nazwie nadpisane przez konfigurację PHP FPM będą dotyczyć środowiska webowego.

W tej sekcji znajdziesz kluczowe parametry odpowiadające opcjom z pliku php.ini. Obejmują one między innymi:

• post_max_size: Maksymalny rozmiar danych przesyłanych metodą POST.
• upload_max_filesize: Limit wielkości pliku możliwego do wysłania.
• date.timezone: Domyślna strefa czasowa PHP.
• display_errors / error_reporting: Określenie, czy błędy będą wyświetlane na stronie oraz jaki poziom błędów będzie raportowany.
• max_execution_time: Limit czasu wykonywania skryptu (w sekundach).
• disable_functions / disable_classes: Wyłączenie określonych funkcji lub klas dla wzmocnienia bezpieczeństwa.
• open_basedir: Ograniczenie dostępu PHP do wskazanych ścieżek w systemie plików. Zaleca się umieszczanie wszystkich projektów w domyślnym katalogu SerwBay /Applications/ServBay/www, co pozwoli wygodnie skonfigurować open_basedir bez ręcznego wymieniania wielu ścieżek.

Wszystkie te opcje możesz edytować bezpośrednio w UI ServBay.

Pełny opis wszystkich możliwych ustawień znajdziesz w oficjalnej dokumentacji PHP: PHP Runtime Configuration.

Konfiguracja modułów rozszerzeń PHP

ServBay posiada preinstalowany zestaw popularnych rozszerzeń, obejmujących m.in. obsługę baz danych, cache, debugowanie czy wsparcie dla frameworków. UI ServBay umożliwia łatwe włączanie/wyłączanie oraz konfigurowanie tych modułów.

Najczęściej używane rozszerzenia dostępne w ServBay to między innymi xDebug, OPcache, ImageMagick, Redis, MongoDB, Phalcon, Swoole oraz wiele innych. ServBay wspiera także liczne inne rozszerzenia, pozwalające na obsługę różnych baz danych (MySQL, PostgreSQL, MongoDB), kolejek zadań, systemów cache itd.

Aby włączyć lub wyłączyć rozszerzenie PHP:

1. W interfejsie konfiguracji PHP przejdź do zakładki „Rozszerzenia” lub podobnej.
2. Odnajdź interesujący Cię moduł (np. xdebug).
3. Przełącz odpowiedni przycisk, aby włączyć lub wyłączyć moduł.
4. W przypadku rozszerzeń posiadających dodatkowe opcje (jak xDebug), możesz bezpośrednio w UI zmodyfikować ich ustawienia, np. xdebug.mode, xdebug.client_port itd.
5. Kliknij „Zapisz”, aby zastosować zmiany.

Pełną listę oraz szczegóły na temat obsługiwanych modułów znajdziesz w dokumentacji ServBay: Lista rozszerzeń PHP (sprawdź zawsze aktualną wersję dokumentu).

Struktura plików konfiguracyjnych PHP (nie zaleca się ręcznej edycji)

Mimo że sugerowanym sposobem zmiany ustawień jest UI ServBay, wiedza o strukturze plików konfiguracyjnych przydaje się do zrozumienia mechanizmów działania PHP.

Pliki konfiguracyjne generowane przez ServBay znajdują się w katalogu /Applications/ServBay/etc/php/<version>/.

• php.ini: plik główny konfiguracji.
• php-fpm.conf: konfiguracja menedżera procesów PHP-FPM.
• conf.d/: pliki .ini do ładowania poszczególnych rozszerzeń.

Przykład struktury pliku php.ini

Plik php.ini korzysta z formatu INI. Oto przykład niektórych opcji:

; Ustawienie limitu pamięci
memory_limit = 256M

; Ustawienie maksymalnego rozmiaru przesyłanych plików
upload_max_filesize = 50M
post_max_size = 50M

; Ustawienie strefy czasowej
date.timezone = "Asia/Shanghai" ; lub "UTC", "America/New_York" itp. – ustaw zgodnie z potrzebami

; Włączenie wyświetlania błędów (tylko dla środowiska developerskiego!)
display_errors = On
error_reporting = E_ALL

; Zmiana maksymalnego czasu wykonywania skryptu
max_execution_time = 300

; Ograniczenie dostępu do określonych katalogów (przykład)
; open_basedir = /Applications/ServBay/www/:/tmp/

Przykład struktury pliku php-fpm.conf

Plik php-fpm.conf zawiera ustawienia globalne oraz ustawienia pul procesów (pool). W ServBay domyślnie jest to pula www.

[global]
; Ścieżka do globalnych logów błędów
error_log = /Applications/ServBay/logs/php/8.3/errors.log

[www]
; Adres i port lub plik socket nasłuchu
listen = /Applications/ServBay/tmp/php-cgi-8.3.sock
listen.backlog = -1
listen.allowed_clients = 127.0.0.1

; Użytkownik i grupa (ServBay zazwyczaj używa bieżącego użytkownika)
; user = servbay-demo
; group = staff

; Sposób zarządzania procesami (static, dynamic, ondemand)
pm = dynamic
pm.max_children = 10       ; Maks. liczba procesów potomnych
pm.start_servers = 2       ; Liczba procesów na starcie
pm.min_spare_servers = 1   ; Min. liczba wolnych procesów
pm.max_spare_servers = 6   ; Maks. liczba wolnych procesów
pm.max_requests = 1024     ; Maks. liczba żądań obsłużonych przez proces przed restartem

; Aktywacja logów wolnych zapytań (slowlog)
request_slowlog_timeout = 5s
slowlog = /Applications/ServBay/logs/php/8.3/slow.log

; Ustawienia PHP nadpisujące opcje z php.ini (przykład)
; php_admin_value[memory_limit] = 128M
; php_admin_flag[display_errors] = on

Przykład ładowania modułu PHP (conf.d/)

Pliki .ini z katalogu conf.d/ służą do ładowania i konfigurowania konkretnych rozszerzeń, np. plik xdebug.ini może wyglądać tak:

[Xdebug]
; Ładowanie rozszerzenia Xdebug
zend_extension = xdebug.so

; Tryb działania Xdebug (debug, develop, profile, trace, coverage)
xdebug.mode=debug,develop

; Sposób uruchamiania debugowania (yes, trigger, develop)
; yes: debugowanie zawsze włączone
; trigger: na podstawie wyzwalacza (np. parametr GET/POST lub cookie)
; develop: tylko funkcje pomocnicze (np. stack trace)
xdebug.start_with_request=yes

; Host i port klienta – służy do połączenia z IDE
xdebug.client_host=localhost
xdebug.client_port=39083

; Ścieżka logu Xdebug
xdebug.log=/Applications/ServBay/logs/xdebug/8.3/xdebug.log

Jeszcze raz podkreślamy: mimo znajomości lokalizacji tych plików nie należy ich edytować ręcznie. Do konfiguracji używaj wyłącznie interfejsu ServBay.

Zastosowanie zmian: restart usługi PHP

Po zmianie konfiguracji w UI ServBay, system zwykle automatycznie wykryje i zastosuje zmiany. W niektórych przypadkach może być wymagany restart usługi PHP, aby zmiany w pełni weszły w życie.

Można to wykonać następująco:

Restart przez interfejs ServBay

1. Otwórz główne okno ServBay.
2. W lewym pasku nawigacji kliknij Pakiety.
3. Odszukaj wersję PHP, której konfigurację modyfikowałeś.
4. Kliknij ikonę restartu (zazwyczaj strzałka w okręgu) przy wybranej wersji PHP.

Restart przez narzędzie servbayctl w terminalu

Dla programistów preferujących terminal, ServBay udostępnia narzędzie servbayctl do zarządzania usługami, w tym ponownego uruchamiania wybranych wersji PHP.

Otwórz Terminal i wykonaj poniższą komendę (zamień 8.3 na wersję PHP, którą chcesz zrestartować):

servbayctl restart php 8.3

Po jej wykonaniu wybrany proces PHP-FPM zostanie zrestartowany, a nowa konfiguracja wejdzie w życie.

Najczęściej zadawane pytania (FAQ)

• Q: Edytowałem ręcznie plik php.ini, czemu zmiana nie działa lub się resetuje?

  • A: ServBay zarządza i generuje pliki konfiguracyjne swoich pakietów. Ręczne poprawki mogą zostać nadpisane przy aktualizacji konfiguracji, restarcie usług lub innych wewnętrznych operacjach. Zawsze korzystaj z UI ServBay, aby mieć trwały i prawidłowy zapis zmian.

• Q: Jak zwiększyć limit pamięci PHP lub rozmiar uploadu?

  • A: Otwórz UI ServBay, przejdź do sekcji Języki -> wybierz wersję PHP. W konfiguracji PHP FPM zmień memory_limit (dotyczy stron WWW), w sekcji php.ini znajdziesz upload_max_filesize oraz post_max_size (dotyczy całego środowiska, w wersji webowej może być nadpisane przez FPM). Po zmianie zapisz ustawienia i zrestartuj PHP.

• Q: Jak włączyć lub skonfigurować Xdebug?

  • A: Otwórz UI ServBay, przejdź do Języki -> wybierz wersję PHP. W sekcji rozszerzeń znajdź xdebug, aktywuj go, a następnie wprowadź odpowiednie ustawienia (xdebug.mode, xdebug.client_host, xdebug.client_port itd.) według potrzeb i wymagań Twojego IDE. Zapisz i zrestartuj PHP.

• Q: Czym różni się php.ini od konfiguracji PHP-FPM? Który plik powinienem edytować?

  • A: php.ini to globalny plik ustawień PHP, obejmujący CLI i środowisko webowe. Plik konfiguracyjny PHP-FPM (php-fpm.conf) dotyczy tylko działania PHP w serwerze webowym, a ustawienia w nim mogą nadpisywać te z php.ini. Jeśli chcesz zmienić ustawienia dla środowiska webowego (np. limit pamięci, czas wykonywania, wyświetlanie błędów), sprawdź sekcję FPM. Jeśli konfigurujesz ustawienia związane z CLI lub ogólne (np. strefa czasowa, wyłączanie funkcji), edytuj php.ini. ServBay oddziela te ustawienia czytelnie w UI.

Podsumowanie

ServBay oferuje bezpieczny i wygodny interfejs do zarządzania konfiguracją PHP, obejmującą php.ini, PHP-FPM oraz liczne rozszerzenia. Wszelkie zmiany – po ich zapisaniu i restarcie usługi PHP – zapewniają pełną zgodność środowiska z wymaganiami projektowymi. Mimo że znajomość struktury plików konfiguracyjnych jest cenna dla zrozumienia działania systemu, praktyczne zmiany należy zawsze wprowadzać poprzez UI ServBay, aby uniknąć nadpisywania ręcznych poprawek. Wykorzystaj potężne możliwości konfiguracji ServBay, by z łatwością dopasować środowisko PHP do dowolnego projektu.