Configurar um aplicativo PHP para o Serviço de Aplicativo do Azure

Artigo
08/31/2023

Mostrar a versão do PHP

Aviso

O PHP no Windows atingiu o fim de sua vida útil em novembro de 2022 e só tem suporte no Serviço de Aplicativo no Linux. Este artigo é apenas para referência..

Este guia mostra como configurar os aplicativos Web PHP, os back-ends móveis e os aplicativos de API no Serviço de Aplicativo do Azure.

Este guia fornece conceitos e instruções essenciais para desenvolvedores do PHP que implantam aplicativos no Serviço de Aplicativo. Se você nunca usou o Serviço de Aplicativo do Azure, siga o Início rápido do PHP e o tutorial de PHP com MySQL primeiro.

Para mostrar a versão atual do PHP, execute o seguinte comando no Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query phpVersion

Observação

Para tratar de um slot de desenvolvimento, inclua o parâmetro --slot seguido pelo nome do slot.

Para mostrar todas as versões do PHP compatíveis, execute o seguinte comando no Cloud Shell:

az webapp list-runtimes --os windows | grep PHP

Este guia mostra como configurar os aplicativos Web PHP, os back-ends móveis e os aplicativos de API no Serviço de Aplicativo do Azure.

Para mostrar a versão atual do PHP, execute o seguinte comando no Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

Observação

Para tratar de um slot de desenvolvimento, inclua o parâmetro --slot seguido pelo nome do slot.

Para mostrar todas as versões do PHP compatíveis, execute o seguinte comando no Cloud Shell:

az webapp list-runtimes --os linux | grep PHP

Definir a versão do PHP

Execute o seguinte comando no Cloud Shell para definir a versão do PHP como 8.1:

az webapp config set --resource-group <resource-group-name> --name <app-name> --php-version 8.1

Execute o seguinte comando no Cloud Shell para definir a versão do PHP como 8.1:

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "PHP|8.1"

Executar o Composer

Se você quiser que o Serviço de Aplicativo execute o Composer no momento da implantação, a maneira mais fácil será incluir o Composer em seu repositório.

Em uma janela de terminal local, altere o diretório para a raiz do repositório e siga as instruções na seção Baixar o Composer para obter o composer.phar na raiz do diretório.

Execute os seguintes comandos (você precisa do npm instalado):

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

A raiz do repositório agora tem dois arquivos adicionais: .deployment e deploy.sh.

Abra o deploy.sh e localize a seção Deployment, que é semelhante a esta:

##################################################################################################################################
# Deployment
# ----------

Adicione a seção de código de que você precisa para executar a ferramenta necessária no final da seção Deployment:

# 4. Use composer
echo "$DEPLOYMENT_TARGET"
if [ -e "$DEPLOYMENT_TARGET/composer.json" ]; then
  echo "Found composer.json"
  pushd "$DEPLOYMENT_TARGET"
  php composer.phar install $COMPOSER_ARGS
  exitWithMessageOnError "Composer install failed"
  popd
fi

Confirme todas as alterações e implante o código usando o Git ou faça a implantação do Zip com a automação de compilação habilitada. O Composer agora deve estar em execução como parte da automação da implantação.

Executar o Grunt/Bower/Gulp

Se você quiser que o Serviço de Aplicativo execute ferramentas de automação populares no momento da implantação, como Grunt, Bower ou Gulp, você precisará fornecer um script de implantação personalizado. O Serviço de Aplicativo executa esse script quando você implanta com o Git ou com a Implantação de zip com a automação de compilação habilitada.

Para habilitar o repositório de modo a executar essas ferramentas, você precisa adicioná-las às dependências no package.json. Por exemplo:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

Em uma janela de terminal local, altere o diretório para a raiz do repositório e execute os seguintes comandos (você precisa do npm instalado):

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

A raiz do repositório agora tem dois arquivos adicionais: .deployment e deploy.sh.

Abra o deploy.sh e localize a seção Deployment, que é semelhante a esta:

##################################################################################################################################
# Deployment
# ----------

Esta seção termina com a execução de npm install --production. Adicione a seção de código de que você precisa para executar a ferramenta necessária no final da seção Deployment:

Bower
Gulp
Grunt

Veja um exemplo no MEAN.js de amostra, em que o script de implantação também executa um comando npm install personalizado.

Bower

Esse snippet de código executa bower install.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

Esse snippet de código executa gulp imagemin.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

Esse snippet de código executa grunt.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

Personalizar a automação de build

Se você implantar seu aplicativo usando Git ou pacotes zip com automação de compilação habilitada, o Serviço de Aplicativo do Azure criará etapas de automação por meio da seguinte sequência:

Executar script personalizado se especificado por PRE_BUILD_SCRIPT_PATH.
Execute php composer.phar install.
Executar script personalizado se especificado por POST_BUILD_SCRIPT_PATH.

PRE_BUILD_COMMAND e POST_BUILD_COMMAND são variáveis de ambiente vazias por padrão. Para executar comandos pré-build, defina PRE_BUILD_COMMAND. Para executar comandos pós-build, defina POST_BUILD_COMMAND.

O exemplo a seguir especifica as duas variáveis para uma série de comandos, separados por vírgulas.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

Para obter variáveis de ambiente adicionais para personalizar a automação de build, confira Configuração do Oryx.

Para obter mais informações sobre como o Serviço de Aplicativo executa e compila aplicativos de PHP no Linux, confira a Documentação do Oryx: Como aplicativos PHP são detectados e compilados.

Personalizar a inicialização

Se desejar, você pode executar um comando personalizado no momento da inicialização do contêiner, executando o seguinte comando no Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<custom-command>"

Acessar variáveis de ambiente

No Serviço de Aplicativo, você pode definir configurações de aplicativo fora do código do aplicativo. Em seguida, pode acessá-las usando o padrão getenv(). Por exemplo, para acessar uma configuração de aplicativo chamada DB_HOST, use o seguinte código:

getenv("DB_HOST")

Alterar raiz do site

A estrutura da Web de sua escolha pode usar um subdiretório como a raiz do site. Por exemplo, a Laravel, usa o subdiretório public/ como raiz do site.

Para personalizar a raiz do site, defina o caminho do aplicativo virtual para o aplicativo usando o comando az resource update. O exemplo a seguir define a raiz do site para o subdiretório public/ no repositório.

az resource update --name web --resource-group <group-name> --namespace Microsoft.Web --resource-type config --parent sites/<app-name> --set properties.virtualApplications[0].physicalPath="site\wwwroot\public" --api-version 2015-06-01

Por padrão, o Serviço de Aplicativo do Azure aponta o caminho do aplicativo virtual raiz ( / ) para o diretório raiz dos arquivos de aplicativo implantados (/).

A estrutura da Web de sua escolha pode usar um subdiretório como a raiz do site. Por exemplo, a Laravel, usa o subdiretório public/ como raiz do site.

A imagem PHP padrão para Serviço de Aplicativo usa Nginx e você altera a raiz do site configurando o servidor Nginx com a diretiva root. Este arquivo de configuração de exemplo contém os seguintes trechos de código que alteram a diretiva root:

server {
    #proxy_cache cache;
    #proxy_cache_valid 200 1s;
    listen 8080;
    listen [::]:8080;
    root /home/site/wwwroot/public; # Changed for Laravel

    location / {            
        index  index.php index.html index.htm hostingstart.html;
        try_files $uri $uri/ /index.php?$args; # Changed for Laravel
    }
    ...

O contêiner padrão usa o arquivo de configuração encontrado em /etc/nginx/sites-available/default. Tenha em mente que qualquer edição que você fizer nesse arquivo será apagada quando o aplicativo for reiniciado. Para fazer uma alteração eficaz entre as reinicializações do aplicativo, adicione um comando de inicialização personalizado como este exemplo:

cp /home/site/wwwroot/default /etc/nginx/sites-available/default && service nginx reload

Esse comando substitui o arquivo de configuração Nginx padrão por um arquivo chamado padrão na raiz do repositório e reinicia o Nginx.

Detectar sessão HTTPS

No Serviço de Aplicativo, a terminação TLS/SSL ocorre nos balanceadores de carga de rede, de modo que todas as solicitações HTTPS chegam ao seu aplicativo como solicitações HTTP não criptografadas. Se a lógica de aplicativo precisar verificar se as solicitações do usuário estão criptografadas ou não, inspecione o cabeçalho X-Forwarded-Proto.

if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
// Do something when HTTPS is used
}

Estrutura Web populares permitem que você acesse informações do X-Forwarded-* no seu padrão de aplicativo básico. Em CodeIgniter, o is_https() verifica o valor de X_FORWARDED_PROTO por padrão.

Personalizar configurações do php.ini

Se você precisar fazer alterações na instalação do PHP, altere qualquer uma das diretivas php.ini seguindo estas etapas.

Observação

A melhor maneira de ver a versão do PHP e a configuração php.ini atual é chamar phpinfo() em seu aplicativo.

Personalizar diretivas diferentes de PHP_INI_SYSTEM

Para personalizar as diretivas PHP_INI_USER, PHP_INI_PERDIR e PHP_INI_ALL (veja diretivas php.ini), adicione um arquivo .user.ini ao diretório raiz do aplicativo.

Adicione as definições de configuração ao arquivo .user.ini usando a mesma sintaxe que você usaria em um arquivo php.ini. Por exemplo, se você quisesse ativar a configuração display_errors e definir a configuração upload_max_filesize para 10M, o arquivo .user.ini conteria este texto:

 ; Example Settings
 display_errors=On
 upload_max_filesize=10M

 ; Write errors to d:\home\LogFiles\php_errors.log
 ; log_errors=On

Reimplante seu aplicativo com as alterações e reinicie-o.

Como alternativa ao uso de um arquivo .user.ini, você pode usar ini_set() no aplicativo para personalizar essas diretivas que não são PHP_INI_SYSTEM.

Para personalizar PHP_INI_USER, PHP_INI_PERDIR e diretivas PHP_INI_ALL para aplicativos Web do Linux, como upload_max_filesize e expose_php, use um arquivo "ini" personalizado. Você pode criá-lo em uma sessão do SSH.

Acesse o site do KUDU https://< sitename.scm.azurewebsites.net>.
Selecione Bash ou SSH no menu superior.
Em Bash/SSH, acesse o diretório "/home/site/wwwroot".
Crie um diretório chamado "ini" (por exemplo, mkdir ini).
Altere o diretório de trabalho atual para a pasta "ini" que você acabou de criar.

Você precisa criar um arquivo "ini" para adicionar suas configurações. Neste exemplo, usamos "extensions.ini". Não há editores de arquivos, como Vi, Vim ou Nano, portanto, você usará o eco para adicionar as configurações ao arquivo. Altere o "upload_max_filesize" de 2M para 50M. Use o comando a seguir para adicionar a configuração e criar um arquivo "extensions.ini" se ainda não existir.

/home/site/wwwroot/ini>echo "upload_max_filesize=50M" >> extensions.ini
/home/site/wwwroot/ini>cat extensions.ini

upload_max_filesize=50M

/home/site/wwwroot/ini>

Em seguida, acesse o portal do Azure e adicione uma Configuração de Aplicativo para verificar o diretório "ini" que você acabou de criar para aplicar a alteração em upload_max_filesize.

Acesse o portal do Azure e selecione o aplicativo PHP Linux do Serviço de Aplicativo.
Selecionar Configurações de Aplicativos para o aplicativo.
Na seção configuração de aplicativo, selecione + Adicionar nova configuração.
No Nome da Configuração do Aplicativo, insira "PHP_INI_SCAN_DIR" e, no valor, insira "/home/site/wwwroot/ini".
Selecione o botão Salvar.

Observação

Se você recompilou uma extensão PHP, como GD, siga as etapas em Recompilando extensões PHP no Serviço de Aplicativo do Azure – Adicionando extensões PHP

Personalizar diretivas PHP_INI_SYSTEM

Para personalizar diretivas PHP_INI_SYSTEM (consulte diretivas php.ini), use a configuração do aplicativo PHP_INI_SCAN_DIR.

Primeiro, execute o seguinte comando no Cloud Shell para adicionar uma configuração de aplicativo chamada PHP_INI_SCAN_DIR:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PHP_INI_SCAN_DIR="d:\home\site\ini"

Navegue até o console do Kudu (https://<app-name>.scm.azurewebsites.net/DebugConsole) e acesse d:\home\site.

Crie um diretório em d:\home\site chamado ini e, em seguida, crie um arquivo .ini no diretório d:\home\site\ini (por exemplo, settings.ini) com as diretivas que você deseja personalizar. Use a mesma sintaxe que você usaria em um arquivo php.ini.

Por exemplo, para alterar o valor de expose_php execute os seguintes comandos:

cd /home/site
mkdir ini
echo "expose_php = Off" >> ini/setting.ini

Para que as alterações entrem em vigor, reinicie o aplicativo.

Para personalizar diretivas PHP_INI_SYSTEM (consulte diretivas php.ini), você não pode usar a abordagem do .htaccess. O Serviço de Aplicativo oferece um mecanismo separado usando a configuração PHP_INI_SCAN_DIR do aplicativo.

Primeiro, execute o seguinte comando no Cloud Shell para adicionar uma configuração de aplicativo chamada PHP_INI_SCAN_DIR:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PHP_INI_SCAN_DIR="/usr/local/etc/php/conf.d:/home/site/ini"

/usr/local/etc/php/conf.d é o diretório padrão em que o php.ini existe. /home/site/ini é o diretório personalizado no qual você adicionará um arquivo .ini personalizado. Separe os valores com um :.

Navegue até a sessão SSH da Web com seu contêiner do Linux (https://<app-name>.scm.azurewebsites.net/webssh/host).

Crie um diretório em /home/site chamado ini e, em seguida, crie um arquivo .ini no diretório /home/site/ini (por exemplo, settings.ini) com as diretivas que você deseja personalizar. Use a mesma sintaxe que você usaria em um arquivo php.ini.

Dica

Nos contêineres internos do Linux no Serviço de Aplicativo, /home é usado como armazenamento compartilhado persistente.

Por exemplo, para alterar o valor de expose_php execute os seguintes comandos:

cd /home/site
mkdir ini
echo "expose_php = Off" >> ini/setting.ini

Para que as alterações entrem em vigor, reinicie o aplicativo.

Habilitar extensões PHP

As instalações internas do PHP contêm as extensões usadas com mais frequência. Você pode habilitar outras extensões da mesma forma que personaliza as diretivas do php.ini.

Observação

A melhor maneira de ver a versão do PHP e a configuração php.ini atual é chamar phpinfo() em seu aplicativo.

Para habilitar extensões adicionais, siga estas etapas:

Adicione um diretório bin ao diretório raiz do aplicativo e coloque os arquivos de extensão .dll nele (por exemplo, mongodb.dll). Verifique se as extensões são compatíveis com a versão do PHP no Azure e também com nts (non-thread-safe) e VC9.

Implante suas alterações.

Siga as etapas em Personalizar diretivas PHP_INI_SYSTEM e adicione as extensões ao arquivo personalizado .ini com as diretivas extension ou zend_extension.

extension=d:\home\site\wwwroot\bin\mongodb.dll
zend_extension=d:\home\site\wwwroot\bin\xdebug.dll

Para que as alterações entrem em vigor, reinicie o aplicativo.

As instalações internas do PHP contêm as extensões usadas com mais frequência. Você pode habilitar outras extensões da mesma forma que personaliza as diretivas do php.ini.

Observação

A melhor maneira de ver a versão do PHP e a configuração php.ini atual é chamar phpinfo() em seu aplicativo.

Para habilitar extensões adicionais, siga estas etapas:

Adicione um diretório bin ao diretório raiz do seu aplicativo e coloque os arquivos de extensão .so nele (por exemplo, mongodb.so). Verifique se as extensões são compatíveis com a versão do PHP no Azure e também com nts (non-thread-safe) e VC9.

Implante suas alterações.

Siga as etapas em Personalizar diretivas PHP_INI_SYSTEM e adicione as extensões ao arquivo personalizado .ini com as diretivas extension ou zend_extension.

extension=/home/site/wwwroot/bin/mongodb.so
zend_extension=/home/site/wwwroot/bin/xdebug.so

Para que as alterações entrem em vigor, reinicie o aplicativo.

Acessar logs de diagnóstico

Use o utilitário error_log () padrão para fazer os logs de diagnóstico aparecerem no Serviço de Aplicativo do Azure.

Para acessar os logs de console gerados dentro do código do aplicativo no Serviço de Aplicativo, ative o log de diagnóstico executando o seguinte comando no Cloud Shell:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

Os valores possíveis para --level são Error, Warning, Info e Verbose. Cada nível seguinte inclui o anterior. Por exemplo: Error inclui apenas mensagens de erro e Verbose inclui todas as mensagens.

Depois que o log de diagnósticos estiver ativado, execute o seguinte comando para ver o fluxo de logs:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

Se você não vir os logs do console imediatamente, verifique novamente após 30 segundos.

Observação

Você também pode inspecionar os arquivos de log do navegador em https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Para interromper o streaming de log a qualquer momento, digite Ctrl+C.

Você pode acessar os logs do console gerados de dentro do contêiner.

Primeiro, ative o log do contêiner executando o seguinte comando:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Substitua <app-name> e <resource-group-name> pelos nomes apropriados para seu aplicativo Web.

Depois que o log do contêiner estiver ativado, execute o seguinte comando para ver o fluxo de log:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

Se você não vir os logs do console imediatamente, verifique novamente após 30 segundos.

Para interromper o streaming de log a qualquer momento, digite Ctrl+C.

Você também pode inspecionar os arquivos de log em um navegador em https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Solução de problemas

Quando um aplicativo PHP que esteja funcionando se comporta de maneira diferente no Serviço de Aplicativo ou tem erros, tente o seguinte:

Acessar o fluxo de log.
Teste o aplicativo localmente no modo de produção. O Serviço de Aplicativo executa os aplicativos no modo de produção, portanto, verifique se o projeto funciona como esperado localmente no modo de produção. Por exemplo:
- Dependendo do composer.json, diferentes pacotes podem ser instalados para o modo de produção (require versus require-dev).
- Determinadas estruturas da Web podem implantar arquivos estáticos de maneira diferente no modo de produção.
- Determinadas estruturas da Web podem usar scripts de inicialização personalizados ao serem executados no modo de produção.
Execute seu aplicativo no Serviço de Aplicativo no modo de depuração. Por exemplo, no Laravel, você pode configurar seu aplicativo para gerar mensagens de depuração em produção definindo a configuração do aplicativo APP_DEBUG como true.

robots933456 em logs

Você poderá ver a seguinte mensagem nos logs de contêiner:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

Você pode ignorar essa mensagem com segurança. /robots933456.txt é um caminho de URL fictício que o Serviço de Aplicativo usa para verificar se o contêiner é capaz de atender a solicitações. Uma resposta 404 indica apenas que o caminho não existe, mas informa ao Serviço de Aplicativo que o contêiner está íntegro e pronto para responder a solicitações.

Próximas etapas

Tutorial: Aplicativo PHP com o MySQL

Perguntas frequentes sobre o Serviço de Aplicativo no Linux

Ou, veja recursos adicionais:

Referência de variáveis de ambiente e configurações de aplicativo

Configurar um aplicativo PHP para o Serviço de Aplicativo do Azure

Mostrar a versão do PHP

Definir a versão do PHP

Executar o Composer

Executar o Grunt/Bower/Gulp

Bower

Gulp

Grunt

Personalizar a automação de build

Personalizar a inicialização

Acessar variáveis de ambiente

Alterar raiz do site

Detectar sessão HTTPS

Personalizar configurações do php.ini

Personalizar diretivas diferentes de PHP_INI_SYSTEM

Personalizar diretivas PHP_INI_SYSTEM

Habilitar extensões PHP

Acessar logs de diagnóstico

Solução de problemas

robots933456 em logs

Próximas etapas

Recursos adicionais