PHP na IIS - Konfiguracja FastCGI i optymalizacja API

Konfiguracja iis php sprowadza się do poprawnego spięcia FastCGI, doboru właściwej kompilacji PHP i ustawienia kilku parametrów, które decydują o stabilności aplikacji. To ważne nie tylko przy klasycznych stronach, ale też przy backendach i API, gdzie błędny handler, zbyt mały limit żądań albo źle ustawione uprawnienia potrafią zatrzymać cały ruch. Poniżej pokazuję, jak to poukładać bez zbędnych skrótów myślowych.

Co naprawdę oznacza integracja PHP z IIS

W praktyce IIS nie „odpala” PHP tak, jak niektórzy wyobrażają to sobie po doświadczeniach z Apache. Serwer przekazuje żądania do osobnego procesu FastCGI, a tym procesem w świecie PHP jest zazwyczaj php-cgi.exe. To dlatego poprawna konfiguracja zaczyna się od mapowania rozszerzenia .php na właściwy executable, a nie od wskazania pliku php.exe.

Jeżeli mam wskazać jedną rzecz, którą początkujący pomijają najczęściej, to jest nią właśnie warstwa pośrednia. PHP na IIS nie jest tylko „instalacją języka”, ale zestawem decyzji: jaki build pobrać, jaką pulę aplikacji ustawić, komu dać dostęp do plików i jak obsłużyć błędy bez generowania fałszywych 500-tek. To prowadzi do wyboru właściwej wersji i właściwego wariantu binariów.

Jak dobrać właściwy pakiet PHP do IIS

W 2026 nie wybierałbym już wersji „byle działało”. Jeśli startujesz nowy projekt, zacznij od gałęzi, która ma jeszcze długi okres wsparcia bezpieczeństwa i jest realnie utrzymywana. Dla nowych wdrożeń najczęściej wybieram PHP 8.5, a jeśli zależy mi na większej przewidywalności zależności, PHP 8.4. PHP 8.3 zostawiam raczej do migracji istniejących aplikacji, a 8.2 traktuję jako wersję, której czas dla nowych projektów już wyraźnie się kończy.

Do IIS wybieraj Non-Thread Safe, bo FastCGI działa właśnie w takim modelu. W praktyce oznacza to, że do mapowania pod IIS używasz php-cgi.exe, a nie php.exe. W tle dochodzi jeszcze jeden szczegół: zgodność z bibliotekami Visual C++ dla danej kompilacji. Jeśli coś po instalacji nie startuje, bardzo często winny jest brak odpowiedniego runtime, a nie sam PHP.

Gdy dobór wersji i binariów masz już zamknięty, można przejść do konfiguracji samego IIS bez zgadywania, co jest przyczyną błędu, a co tylko skutkiem ubocznym.

Jak przejść przez konfigurację bez zbędnych poprawek

Najprościej myśleć o tym jak o krótkiej sekwencji kroków, a nie jak o „magii w panelu”. Najpierw IIS musi mieć komponenty potrzebne do obsługi CGI/FastCGI, potem trzeba wskazać właściwy interpreter PHP, a na końcu sprawdzić, czy serwer faktycznie wykonuje kod, zamiast tylko go serwować jako zwykły plik.

1. Włącz rolę IIS i upewnij się, że masz doinstalowany moduł CGI/FastCGI.
2. Pobierz odpowiedni build PHP dla Windows i rozpakuj go do stałej lokalizacji, na przykład C:\PHP.
3. Skopiuj bazowy plik konfiguracji do php.ini i ustaw w nim podstawowe parametry pod środowisko produkcyjne lub testowe.
4. W IIS Manager przejdź do Handler Mappings i dodaj mapowanie dla *.php.
5. Jako moduł wybierz FastCgiModule, a jako executable wskaż C:\PHP\php-cgi.exe.
6. Jeśli kreator zapyta o utworzenie aplikacji FastCGI, potwierdź i ustaw limity procesów.
7. Przetestuj konfigurację prostym plikiem phpinfo(), a po teście usuń go z serwera.

W praktyce dobrze działa też prosta zasada: jeden osobny application pool na jedną aplikację albo co najmniej na jeden projekt. Dzięki temu łatwiej sterować pamięcią, recyklingiem i uprawnieniami. Jeśli wszystko pakujesz do wspólnej puli, trudniej potem odsiać, czy problem pochodzi z aplikacji, biblioteki czy z samej konfiguracji IIS.

Po takim wdrożeniu najczęściej zaczynają się już nie problemy z samym uruchomieniem PHP, ale z jego zachowaniem pod ruchem. I właśnie tam robi różnicę dobrze ustawiony php.ini.

Jak ustawić backend i API, żeby nie walczyć z ograniczeniami serwera

Jeśli na IIS działa backend albo API, nie traktuję php.ini jak pliku „od święta”. To jest jedna z ważniejszych części całego wdrożenia, bo decyduje o tym, czy błędy będą czytelne, czy procesy będą się odnawiać, a aplikacja będzie zachowywać się stabilnie po kilku tysiącach żądań.

Ustawienia, które poprawiam najpierw

• fastcgi.impersonate = 1 - IIS może wtedy pracować w kontekście tożsamości obsługującej żądanie, co pomaga przy dostępie do plików i izolacji aplikacji.
• fastcgi.logging = 0 - bez tego drobne komunikaty na stderr potrafią kończyć się błędami 500, mimo że sama aplikacja logicznie działa.
• display_errors = Off - na produkcji nie pokazuję błędów użytkownikowi, tylko zapisuję je do logu.
• log_errors = On - bez logowania diagnostyka backendu i API szybko robi się zgadywaniem.
• memory_limit i max_execution_time - ustawiam je pod realny profil obciążenia, a nie „na wszelki wypadek”.

Przeczytaj również: Backend i API - Jak wybrać stos technologiczny?

Recykling procesów, który nie psuje wydajności

Przy FastCGI warto ustawić spójnie instanceMaxRequests oraz zmienną PHP_FCGI_MAX_REQUESTS. Dokumentacja wskazuje wartość 10000 jako typowy punkt odniesienia i to jest sensowny start, zwłaszcza dla stabilnych aplikacji. Ja zwykle zaczynam od 10000, a przy cięższych rozszerzeniach albo podejrzanych wyciekach pamięci schodzę niżej, zamiast trzymać procesy zbyt długo.

To ma znaczenie szczególnie dla API, które obsługuje dużo krótkich żądań. Lepiej odświeżyć proces kontrolowanie niż czekać, aż zacznie zachowywać się niestabilnie pod wpływem długiej pracy. Właśnie dlatego recykling nie jest tu detalem administracyjnym, tylko częścią jakości działania backendu.

Gdy procesy są już ustawione rozsądnie, pozostaje jeszcze warstwa adresów i limitów. To ona decyduje, czy API będzie wygodne w użyciu, czy zacznie się wykładać na zbyt długich URL-ach albo zbyt dużych payloadach.

Jak przygotować adresy i limity pod API, żeby wszystko działało przewidywalnie

Na IIS bardzo dobrze sprawdza się model front controllera, czyli jedna główna ścieżka wejścia, która rozdziela ruch wewnątrz aplikacji. W praktyce oznacza to najczęściej, że adresy typu /api/users/42 trafiają do jednego pliku startowego, a dopiero kod PHP decyduje, co zrobić z żądaniem. Do takiego układu przydaje się moduł URL Rewrite, bo pozwala pisać czytelne reguły bez dokładania końcówek .php do każdego endpointu.

To jest ważne zwłaszcza w projektach API, gdzie liczy się spójność i łatwa obsługa wersjonowania. Ja wolę utrzymywać endpointy krótkie, przewidywalne i odporne na zmiany struktury plików w aplikacji. Dzięki temu backend można refaktoryzować bez rozbijania całego publicznego interfejsu.

Druga rzecz to limity po stronie serwera. Domyślny limit treści żądania w IIS wynosi 30 000 000 bajtów, czyli około 28,6 MB. Limit długości query stringu to 2048 bajtów, a limit URL to 4096 bajtów. Dla zwykłego API to zwykle wystarcza, ale przy uploadach, większych payloadach JSON albo złożonych parametrach filtra trzeba te wartości świadomie podnieść, zamiast liczyć na to, że serwer „sam się domyśli”.

Jeśli aplikacja przyjmuje duże pliki lub rozbudowane żądania REST, ustawiam limity na dwóch poziomach: w IIS i w samej aplikacji. To ważne, bo sam serwer może przepuścić ruch, ale backend i tak może go odrzucić własnym walidatorem. Najlepszy efekt daje spójna polityka, a nie pojedyncza poprawka w jednym miejscu.

Gdy to wszystko jest już na miejscu, pozostaje uporządkować typowe błędy. I właśnie tutaj najłatwiej zaoszczędzić godziny diagnozy.

Najczęstsze błędy, które widzę przy wdrożeniach

W większości wdrożeń problemy powtarzają się zaskakująco podobnie. Poniżej zestawiam te, które widzę najczęściej, wraz z krótką diagnozą i tym, co sprawdzam w pierwszej kolejności.

Do tego dochodzi jeszcze jeden klasyk: zła architektura binariów, czyli mieszanie 32-bitowego PHP z 64-bitowym środowiskiem albo brak zgodnego runtime Visual C++. To akurat łatwo przeoczyć, bo objawy bywają niejednoznaczne. Jeśli po poprawnej konfiguracji nadal nic nie działa, właśnie tam zaglądam jako pierwsze.

Po wyłapaniu tych błędów łatwiej odpowiedzieć sobie na ważniejsze pytanie: czy IIS jest w ogóle właściwą warstwą dla danego projektu PHP.

Kiedy IIS ma sens w projekcie PHP, a kiedy lepiej go odpuścić

IIS ma duży sens tam, gdzie środowisko i tak jest osadzone w Windowsie. Dobrze sprawdza się przy integracji z Active Directory, w firmach opartych o Microsoft stack, przy projektach, które muszą współistnieć z .NET, albo wtedy, gdy zespół opsowy naprawdę zna IIS i chce centralnie zarządzać serwerem. W takim układzie to nie jest kompromis, tylko logiczny wybór.

Są jednak scenariusze, w których IIS zaczyna bardziej przeszkadzać niż pomagać. Jeśli cały ekosystem jest Linux-first, jeśli zespół bazuje na dziesiątkach poradników dla Nginx albo Apache, albo jeśli aplikacja ma bardzo dynamiczną, kontenerową ścieżkę wdrożeń, IIS może dokładać warstwę mentalnego i operacyjnego tarcia. Wtedy koszt wejścia bywa wyższy niż zysk.

Przy backendzie i API najważniejsze jest dla mnie jedno: serwer ma być przewidywalny. Jeśli wybierasz IIS, trzymaj się FastCGI, NTS, osobnych puli aplikacji, sensownych limitów i prostego routingu przez front controller. Taki zestaw daje stabilne wdrożenie i nie wymaga codziennego gaszenia pożarów, a to w praktyce jest ważniejsze niż sama elegancja konfiguracji.

Jeśli miałbym wskazać punkt startowy na dziś, wybrałbym PHP 8.5 NTS x64, osobny application pool dla aplikacji, mapping na php-cgi.exe i od razu dopasował limity pod realny ruch API. Resztę da się dopracować później, ale tych podstaw lepiej nie odkładać, bo właśnie one decydują o tym, czy wdrożenie będzie spokojne, czy nerwowe.