Integração com PHP no Apache: visão geral com PHP-FPM e mod_php

Vise3o geral: como o Apache executa PHP

O Apache, por si sf3, ne3o interpreta cf3digo PHP. Para que arquivos .php sejam executados (e ne3o baixados como texto), o Apache precisa encaminhar essas requisie7f5es para um interpretador PHP. As duas abordagens mais comuns se3o:

• mod_php: o interpretador PHP roda dentro do processo do Apache (mf3dulo carregado no servidor web).
• PHP-FPM + proxy_fcgi: o Apache atua como proxy e encaminha requisie7f5es PHP para um servie7o separado (PHP-FPM), via socket Unix ou TCP.

Quando usar mod_php

• Ambientes simples/legados onde o empacotamento do sistema ainda oferece libapache2-mod-php (Debian/Ubuntu) ou equivalente.
• Quando vocea ne3o precisa de pools separados por site/usue1rio e quer menos pee7as para administrar.

Pontos de atene7e3o: o Apache tende a ficar acoplado e0 verse3o do PHP, e em MPM event/worker pode haver restrie7f5es (muitas distros preferem FPM). Tambe9m fica mais difedcil isolar sites com configurae7f5es/pools diferentes.

Quando usar PHP-FPM (proxy_fcgi)

• Hospedagem com ve1rios sites, necessidade de isolamento por pool, limites de recursos e configurae7f5es diferentes por aplicae7e3o.
• Ambientes modernos onde se quer desacoplar o ciclo de vida do PHP do Apache (reiniciar FPM sem reiniciar Apache, trocar verse3o do PHP com menos impacto).
• Melhor compatibilidade com MPM event/worker e cene1rios de alto tre1fego.

Arquivos e pee7as de configurae7e3o que vocea vai encontrar

mod_php (exemplos comuns)

• mods-available/php*.load e mods-available/php*.conf (Debian/Ubuntu): carregamento do mf3dulo e ajustes.
• Diretivas como SetHandler / AddHandler podem aparecer em arquivos do site (VirtualHost) ou em conf global.

PHP-FPM + Apache (proxy_fcgi)

• mods-available/proxy_fcgi.load e mods-available/proxy_fcgi.conf (mf3dulo que faz o encaminhamento FastCGI).
• mods-available/proxy.load (dependeancia do proxy).
• Config do PHP-FPM: tipicamente em /etc/php/<verse3o>/fpm/pool.d/*.conf (Debian/Ubuntu) ou caminhos equivalentes na sua distro.
• Socket do FPM: frequentemente algo como /run/php/php<verse3o>-fpm.sock (Unix) ou 127.0.0.1:9000 (TCP).

Laboratf3rio: validar execue7e3o com phpinfo()

Este teste serve para confirmar rapidamente se o Apache este1 executando PHP e por qual me9todo. Importante: phpinfo() expf5e muitas informae7f5es do ambiente. Use apenas para validae7e3o e remova em seguida.

1) Criar o arquivo de teste

No DocumentRoot do seu site, crie um arquivo info.php:

<?php
phpinfo();

2) Acessar pelo navegador

Acesse http://SEU_HOST/info.php. O resultado esperado e9 uma pe1gina com informae7f5es do PHP. Se o navegador fizer download do arquivo ou mostrar o cf3digo, he1 problema de handler (ver diagnf3stico mais abaixo).

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

3) Confirmar se e9 mod_php ou FPM

• Se aparecer algo como Server API = Apache 2.0 Handler, e9 comum ser mod_php.
• Se aparecer Server API = FPM/FastCGI, vocea este1 usando PHP-FPM.

4) Remover o arquivo de teste (obrigatf3rio)

Apague info.php assim que terminar a validae7e3o.

Configurae7e3o pre1tica: PHP-FPM com proxy_fcgi e FilesMatch

A seguir este1 um padre3o comum para encaminhar apenas arquivos .php ao PHP-FPM. A ideia e9: quando o Apache encontrar um arquivo que termina com .php, ele usa um handler FastCGI apontando para o socket/porta do FPM.

1) Garantir mf3dulos necesse1rios no Apache

Vocea precisa de proxy e proxy_fcgi habilitados. Em sistemas Debian/Ubuntu, costuma ser:

sudo a2enmod proxy proxy_fcgi
sudo systemctl reload apache2

Em outras distros, a habilitae7e3o pode ser via arquivo de mf3dulo/carregamento e reinedcio do servie7o.

2) Conferir o endpoint do PHP-FPM (socket ou TCP)

Verifique como o pool do FPM este1 configurado (diretiva listen). Exemplos:

• Socket Unix: listen = /run/php/php8.2-fpm.sock
• TCP: listen = 127.0.0.1:9000

Esse valor e9 o que vocea vai usar no SetHandler.

3) Configurar o handler no VirtualHost (recomendado)

Dentro do bloco do seu site (VirtualHost), adicione um FilesMatch para .php. Exemplo usando socket Unix:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/php8.2-fpm.sock|fcgi://localhost/"
</FilesMatch>

Exemplo usando TCP:

<FilesMatch \.php$>
    SetHandler "proxy:fcgi://127.0.0.1:9000"
</FilesMatch>

Observae7e3o: o trecho fcgi://localhost/ no caso do socket e9 um padre3o comum para completar a URL do handler; o caminho real do script vem da requisie7e3o e do mapeamento do Apache.

4) Recarregar e testar

sudo apachectl configtest
sudo systemctl reload apache2

Recrie temporariamente o info.php (se je1 tiver removido) e teste novamente. Ao final, remova.

Configurae7e3o pre1tica: mod_php (vise3o geral)

Com mod_php, o Apache carrega o mf3dulo do PHP e associa .php ao handler do prf3prio Apache. Em Debian/Ubuntu, um caminho comum e9 instalar e habilitar o pacote do mf3dulo (ex.: libapache2-mod-php), e o sistema cria/ativa arquivos como php*.load e php*.conf.

Um exemplo conceitual de associae7e3o (pode variar por distro/pacote) seria algo como:

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Na pre1tica, vocea normalmente ne3o precisa escrever isso manualmente se o pacote do mod_php je1 instala a configurae7e3o padre3o.

Diagnf3stico: erros tedpicos e como identificar

1) O navegador faz download do .php (ou mostra o cf3digo fonte)

Causa mais comum: o Apache este1 servindo o arquivo como contefado este1tico, sem handler PHP configurado.

• Em FPM: faltou o bloco FilesMatch com SetHandler, ou os mf3dulos proxy/proxy_fcgi ne3o este3o habilitados.
• Em mod_php: o mf3dulo ne3o este1 carregado/habilitado, ou vocea este1 usando um MPM incompatedvel com a forma como o pacote foi montado.

Como confirmar: verifique o error.log do site e procure mensagens sobre handler desconhecido, mf3dulo ausente ou diretivas ignoradas.

2) Erro 503 Service Unavailable / timeout ao acessar .php (cene1rio FPM)

Causas comuns:

• PHP-FPM parado ou ne3o respondendo.
• Endpoint incorreto: socket/porta no Apache ne3o bate com o listen do pool.
• Fila/limites do FPM: pool sem workers suficientes, requisie7f5es acumulando e estourando timeout.

O que checar:

• Status do servie7o do FPM e logs do FPM.
• No Apache error.log, mensagens como AH01079: failed to make connection to backend, AH01102: error reading status line from remote server ou timeouts.
• Se estiver usando TCP, teste conectividade local (ex.: ss -lntp | grep 9000). Se for socket, verifique se o arquivo existe em /run/php/....

3) Permisse3o negada no socket do PHP-FPM

Quando o Apache tenta acessar um socket Unix do FPM, ele precisa ter permisse3o de leitura/escrita no arquivo do socket. Se o socket existir mas o Apache ne3o conseguir acesse1-lo, e9 comum ver erros no Apache semelhantes a (13)Permission denied ao conectar no backend.

O que ajustar (no pool do FPM):

• listen.owner e listen.group: devem permitir que o usue1rio/grupo do Apache acesse o socket.
• listen.mode: permissf5es do arquivo do socket (ex.: 0660).

Exemplo (ajuste para o usue1rio/grupo do seu Apache):

listen = /run/php/php8.2-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Depois, reinicie/recarregue o PHP-FPM para recriar o socket com as permissf5es corretas.

4) Arquivo existe, mas retorna 404 ou executa o script errado

Em FPM, mapeamento incorreto pode fazer o backend ne3o encontrar o script. Isso pode acontecer se o site tiver aliases/regras e o handler ne3o estiver aplicado no contexto correto.

• Garanta que o FilesMatch esteja dentro do VirtualHost correto.
• Evite aplicar handler globalmente para caminhos que ne3o deveriam executar PHP (por exemplo, diretf3rios de upload).

Recomendae7f5es mednimas para ne3o expor informae7f5es sensedveis

• Ne3o deixe info.php (ou qualquer endpoint de diagnf3stico) publicado em produe7e3o.
• Em caso de necessidade tempore1ria, restrinja por IP/autenticae7e3o e remova logo apf3s o teste.
• Evite exibir erros detalhados para o usue1rio final (erros devem ir para logs). Ajustes de display_errors devem ser pensados para produe7e3o.
• Ne3o aplique handler PHP em diretf3rios onde usue1rios possam enviar arquivos (uploads). Garanta que esses diretf3rios ne3o executem scripts.
• Revise permissf5es do socket/porta do FPM para que apenas o servidor web consiga acessar (evite expor o FPM em rede sem necessidade).