Existe uma diferença importante entre um site em PHP e uma aplicação em PHP, e ela aparece exatamente na hora de publicar.

Um site tradicional é um conjunto de arquivos: você envia para o servidor e ele funciona. Uma aplicação construída com framework não é assim — ela tem dependências que precisam ser instaladas, comandos que precisam ser executados, uma estrutura de pastas que espera uma configuração específica e, frequentemente, processos que precisam ficar rodando.

Quem tenta publicar uma aplicação como se publicasse um site esbarra em uma sequência previsível de problemas. Este guia percorre o que efetivamente muda.

A estrutura de pastas é diferente

O primeiro obstáculo, e o mais comum.

Em um site tradicional, todos os arquivos ficam na pasta que o servidor web publica. Em uma aplicação com framework, a maior parte do código não deve ser acessível pela internet. Apenas uma pasta específica — normalmente chamada de pública — contém o ponto de entrada e os arquivos que o visitante pode acessar.

O restante fica fora dela: código da aplicação, configurações, dependências, arquivos temporários.

Quando isso é configurado errado, acontece um de dois problemas:

• A aplicação não funciona, porque o servidor procura o ponto de entrada no lugar errado.
• A aplicação funciona e expõe arquivos que não deveriam ser acessíveis — incluindo o arquivo de configuração, que costuma conter credenciais do banco de dados.

O segundo é o cenário grave: um arquivo de configuração acessível pela internet entrega as credenciais do banco a qualquer pessoa. Vale verificar isso explicitamente após qualquer publicação — tentar acessar o arquivo pelo navegador e confirmar que ele não é servido.

Configurar isso corretamente exige acesso à configuração do servidor web, que é uma das razões pelas quais aplicações com framework pedem mais que uma hospedagem comum — o assunto do artigo sobre hospedagem compartilhada ou Cloud Server para PHP.

Dependências não vão junto

A segunda diferença fundamental.

Aplicações modernas usam bibliotecas de terceiros, declaradas em um arquivo e instaladas por uma ferramenta própria. Essas bibliotecas normalmente não são enviadas junto com o código — elas são instaladas no servidor durante a publicação.

Isso muda o processo de duas formas:

Existe uma etapa de instalação. Enviar os arquivos não basta: é preciso executar o comando que baixa e instala as dependências na versão correta.

A versão importa. Existe um arquivo que registra exatamente quais versões foram testadas. Instalar respeitando esse registro garante que o servidor use as mesmas versões do ambiente de desenvolvimento. Ignorá-lo permite que uma atualização inesperada de biblioteca quebre a aplicação em produção.

Há ainda uma escolha de onde instalar:

• No servidor, durante a publicação: mais simples, exige que a ferramenta esteja disponível e que haja acesso à internet a partir do servidor.
• Em outro lugar, enviando o resultado pronto: evita executar instalações em produção e torna a publicação mais previsível, ao custo de um passo a mais no processo.

A segunda opção é preferível em aplicações críticas, porque remove uma dependência externa do momento da publicação — se o repositório de bibliotecas estiver indisponível, a publicação não falha.

Comandos que precisam rodar

Aplicações com framework têm etapas de publicação que não existem em um site.

As mais comuns:

1. Instalar dependências, como descrito acima.
2. Aplicar migrações de banco de dados, criando ou alterando tabelas conforme a nova versão exige.
3. Gerar caches de configuração e rotas, que aceleram a aplicação em produção.
4. Publicar arquivos de interface, quando o projeto tem uma etapa de construção de front-end.
5. Limpar caches antigos, para que a aplicação não continue usando a configuração anterior.
6. Reiniciar processos de fila, que continuam executando a versão antiga do código até serem reiniciados.

O item 6 é o mais esquecido e produz um sintoma confuso: a aplicação foi atualizada, mas as tarefas em segundo plano continuam se comportando como antes. Processos de fila carregam o código na memória ao iniciar e não percebem que ele mudou.

Sobre migrações, vale a mesma ressalva registrada no artigo sobre Django, Flask ou FastAPI: a ordem importa, e escrever migrações compatíveis com as duas versões do código é o que evita janela de erro durante a publicação.

E sobre os caches de configuração: eles aceleram, mas congelam os valores no momento da geração. Alterar uma configuração depois disso não tem efeito até que o cache seja regenerado — outra fonte clássica de confusão.

Configuração fica fora do código

Uma prática que já é padrão e vale reforçar, porque a violação dela é comum.

Credenciais de banco, chaves de integração e endereços de serviços não pertencem ao código. Eles ficam em variáveis de ambiente, definidas por ambiente, de modo que o mesmo código rode em desenvolvimento, homologação e produção com valores diferentes.

Três cuidados práticos:

• O arquivo de configuração nunca vai para o controle de versão. Um exemplo sem valores reais serve de referência.
• Permissões restritas no arquivo, e ele fora da pasta pública.
• Chave de aplicação preservada. Alguns frameworks usam uma chave para criptografar dados; gerá-la novamente em produção torna ilegível o que já estava criptografado.

O terceiro item produz um incidente sério e evitável: sessões invalidadas e dados criptografados perdidos porque alguém rodou o comando de geração de chave em um servidor que já estava em produção.

Processos permanentes

A diferença que mais impacta a escolha de ambiente.

Aplicações modernas raramente se limitam a responder requisições. Elas costumam ter:

• Processos de fila, executando tarefas em segundo plano — o conceito está no artigo sobre o que é uma fila de tarefas.
• Uma tarefa agendada que aciona o agendador interno do framework, normalmente a cada minuto.
• Processos de longa duração para recursos específicos.

Isso exige duas coisas do ambiente:

Supervisão. Processos morrem — por erro, por consumo de memória, por reinicialização do servidor. Alguém precisa reiniciá-los automaticamente, ou a aplicação para de processar tarefas sem que nada indique isso.

Permissão para manter processos ativos, que ambientes compartilhados normalmente não oferecem.

Um detalhe operacional relevante: processos de fila devem ser reiniciados periodicamente, mesmo funcionando. Eles acumulam memória ao longo do tempo, e reinícios programados evitam que isso vire problema.

Permissões de arquivo

Um ponto pequeno que causa problemas desproporcionais.

Aplicações com framework escrevem em disco: arquivos temporários, caches, registros, uploads. Essas pastas precisam de permissão de escrita para o usuário sob o qual o servidor web executa.

Os erros típicos:

• Permissão insuficiente, e a aplicação falha ao tentar escrever — frequentemente com uma mensagem genérica.
• Permissão excessiva, liberando escrita para todos, o que é um risco de segurança.
• Proprietário errado, quando os arquivos foram enviados por um usuário e o servidor executa como outro.
• Pasta de uploads com execução permitida, que transforma um envio de arquivo em execução de código.

O último é o mais grave e merece verificação explícita: a pasta onde usuários enviam arquivos não deve permitir a execução deles. É um dos vetores mais conhecidos de comprometimento de aplicações web.

Um processo de publicação

Consolidando em uma sequência:

1. Coloque em modo de manutenção, se a aplicação oferecer, para evitar acessos durante a atualização.
2. Faça backup do banco de dados e dos arquivos enviados por usuários.
3. Envie o código novo.
4. Instale as dependências, respeitando o registro de versões.
5. Aplique as migrações, com atenção à compatibilidade.
6. Limpe e regenere os caches de configuração e rotas.
7. Ajuste permissões das pastas de escrita.
8. Reinicie os processos de fila.
9. Saia do modo de manutenção.
10. Verifique: uma página pública, uma área interna, um envio de formulário e uma tarefa de fila.

O passo 10 é o que separa publicar de concluir. Confirmar que a aplicação responde não é suficiente — é preciso verificar que as tarefas em segundo plano voltaram a ser processadas, porque é justamente isso que falha em silêncio.

E vale a recomendação geral: teste esse processo em um ambiente de homologação antes, especialmente na primeira vez. O procedimento completo está no artigo sobre o que é ambiente de homologação.

Erros comuns e seus sintomas

Sintoma	Causa provável
Página em branco ou erro genérico	Permissão de escrita ou dependência faltando
Arquivo de configuração acessível	Pasta pública configurada incorretamente
Alteração de configuração sem efeito	Cache de configuração não regenerado
Tarefas em segundo plano com código antigo	Processos de fila não reiniciados
Sessões e dados criptografados perdidos	Chave de aplicação regenerada
Agendamentos não executam	Tarefa agendada do sistema não configurada
Funciona local e falha em produção	Versões de dependências diferentes

A segunda linha merece verificação imediata em qualquer aplicação recém-publicada, pela gravidade da exposição.

Conclusão

Publicar uma aplicação PHP construída com framework não é enviar arquivos. É executar uma sequência: instalar dependências na versão registrada, aplicar migrações, regenerar caches, ajustar permissões e reiniciar os processos que executam tarefas em segundo plano.

Duas verificações evitam os problemas mais graves: confirmar que o arquivo de configuração não é acessível pela internet, porque ele contém as credenciais do banco; e confirmar que a pasta de uploads não permite execução, porque é um vetor conhecido de comprometimento.

E um sintoma que vale conhecer de antemão: se a aplicação foi atualizada mas as tarefas em segundo plano continuam se comportando como antes, os processos de fila não foram reiniciados. Se o seu projeto exige esse tipo de publicação, conheça o Cloud Server para PHP da TBF Host e avalie o ambiente adequado.

Perguntas frequentes

Por que minha aplicação PHP com framework não funciona ao enviar os arquivos?

Porque ela não é um conjunto de arquivos prontos. É preciso instalar as dependências no servidor, configurar a pasta pública como raiz do site, aplicar migrações de banco, gerar caches e ajustar permissões de escrita. Enviar o código é apenas uma das etapas.

Qual pasta deve ser a raiz do site em uma aplicação com framework?

A pasta pública, que contém o ponto de entrada e os arquivos acessíveis ao visitante. Todo o restante — código, configurações, dependências — deve ficar fora dela. Configurar errado ou não funciona, ou expõe arquivos que não deveriam ser acessíveis, incluindo o de configuração.

Meu arquivo de configuração pode ser acessado pela internet. Isso é grave?

É muito grave: ele costuma conter as credenciais do banco de dados e chaves de integração. Isso acontece quando a raiz do site aponta para a pasta errada. Vale verificar explicitamente após qualquer publicação, tentando acessar o arquivo pelo navegador e confirmando que ele não é servido.

Preciso enviar as dependências junto com o código?

Normalmente não. Elas são instaladas no servidor durante a publicação, respeitando o arquivo que registra as versões testadas. Alternativamente, é possível instalá-las em outro lugar e enviar o resultado pronto, o que torna a publicação mais previsível por não depender do repositório externo naquele momento.

Alterei uma configuração e nada mudou. Por quê?

Provavelmente o cache de configuração não foi regenerado. Frameworks geram caches que aceleram a aplicação em produção, mas congelam os valores no momento da geração. Alterações posteriores só têm efeito depois que o cache é limpo e gerado novamente.

Atualizei a aplicação mas as tarefas em segundo plano não mudaram de comportamento.

Os processos de fila não foram reiniciados. Eles carregam o código na memória ao iniciar e continuam executando a versão antiga até serem reiniciados. É a etapa mais esquecida em publicações de aplicações com framework.

Por que não devo regenerar a chave de aplicação em produção?

Porque alguns frameworks a usam para criptografar dados. Gerar uma nova torna ilegível tudo o que já estava criptografado com a anterior — incluindo sessões ativas e informações armazenadas. É um incidente sério e totalmente evitável.

Quais permissões de arquivo uma aplicação PHP precisa?

Permissão de escrita, para o usuário sob o qual o servidor web executa, nas pastas de cache, registros, arquivos temporários e uploads. Permissão insuficiente causa falhas com mensagens genéricas; permissão excessiva é risco de segurança. E a pasta de uploads nunca deve permitir execução de arquivos.