Configuración de una aplicación de PHP para Azure App Service

Artículo
08/31/2023

Visualización de la versión de PHP

Advertencia

PHP en Windows alcanzó el final de su vida útil en noviembre de 2022 y solo se admite en App Service en Linux. Este artículo sirve solo como referencia..

En esta guía, se explica cómo se configuran las aplicaciones web de PHP, los back-ends para dispositivos móviles y las aplicaciones de API de Azure App Service.

Esta guía incluye conceptos clave e instrucciones para los desarrolladores de PHP que implementan aplicaciones en App Service. Si nunca ha usado Azure App Service, siga primero la guía de inicio rápido de PHP y el tutorial de PHP con MySQL.

Para mostrar la versión actual de PHP, ejecute el siguiente comando en Cloud Shell:

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

Nota

Para dirigirse a una ranura de desarrollo, incluya el parámetro --slot seguido del nombre de la ranura.

Para mostrar todas las versiones compatibles de PHP, ejecute el siguiente comando en Cloud Shell:

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

En esta guía, se explica cómo se configuran las aplicaciones web de PHP, los back-ends para dispositivos móviles y las aplicaciones de API de Azure App Service.

Para mostrar la versión actual de PHP, ejecute el siguiente comando en Cloud Shell:

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

Nota

Para dirigirse a una ranura de desarrollo, incluya el parámetro --slot seguido del nombre de la ranura.

Para mostrar todas las versiones compatibles de PHP, ejecute el siguiente comando en Cloud Shell:

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

Establecer la versión de PHP

Ejecute el siguiente comando en Cloud Shell para establecer la versión 8.1 de PHP:

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

Ejecute el siguiente comando en Cloud Shell para establecer la versión 8.1 de PHP:

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

Ejecución de Composer

Si quiere que App Service ejecute Composer en el momento de la implementación, la manera más fácil es incluir Composer en el repositorio.

En una ventana de terminal local, cambie el directorio a la raíz del repositorio y siga las instrucciones que se indican en Descarga de Composer para descargar composer.phar a la raíz del directorio.

Ejecute los siguientes comandos (necesita tener instalado npm):

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

La raíz del repositorio ahora tiene dos archivos adicionales: .deployment y deploy.sh.

Abra deploy.sh y busque la sección Deployment, que tiene el siguiente aspecto:

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

Agregue la sección de código que necesita para ejecutar la herramienta necesaria al final de la sección 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 todos los cambios e implemente el código mediante Git o realice la implementación desde un archivo ZIP con la automatización de compilaciones habilitada. Composer ahora debería estar funcionando como parte de la automatización de la implementación.

Ejecutar Grunt, Bower o Gulp

Si quiere que App Service ejecute herramientas de automatización populares en el momento de la implementación, como Grunt, Bower o Gulp, deberá suministrar un script de implementación personalizado. App Service ejecuta este script cuando se implementa con Git o con la implementación desde un archivo ZIP con la automatización de compilaciones habilitada.

Para habilitar que el repositorio ejecute estas herramientas, deberá agregarlas a las dependencias en el archivo package.json. Por ejemplo:

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

Desde una ventana de terminal local, cambie el directorio a la raíz del repositorio y ejecute los siguientes comandos (debe tener instalado npm):

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

La raíz del repositorio ahora tiene dos archivos adicionales: .deployment y deploy.sh.

Abra deploy.sh y busque la sección Deployment, que tiene el siguiente aspecto:

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

En esta sección termina con la ejecución de npm install --production. Agregue la sección de código que necesita para ejecutar la herramienta necesaria al final de la sección Deployment:

Bower
Gulp
Grunt

Consulte un ejemplo en la muestra de MEAN.js, donde el script de implementación también ejecuta un comando npm install personalizado.

Bower

Este fragmento de código ejecuta 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

Este fragmento de código ejecuta 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

Este fragmento de código ejecuta grunt.

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

Personalización de la automatización de compilaciones

Si implementa la aplicación mediante paquetes Git o zip con la automatización de compilaciones activada, la automatización de compilaciones de App Service se ejecutará en este orden:

Ejecute el script personalizado si lo especifica PRE_BUILD_SCRIPT_PATH.
Ejecute php composer.phar install.
Ejecute el script personalizado si lo especifica POST_BUILD_SCRIPT_PATH.

PRE_BUILD_COMMAND y POST_BUILD_COMMAND son variables de entorno que, de forma predeterminada, están vacías. Para ejecutar comandos anteriores a la compilación, defina PRE_BUILD_COMMAND. Para ejecutar comandos posteriores a la compilación, defina POST_BUILD_COMMAND.

En el ejemplo siguiente se especifican las dos variables para una serie de comandos, separados por comas.

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 obtener más variables de entorno para personalizar la automatización de compilaciones, consulte la configuración de Oryx.

Para más información sobre cómo se ejecuta App Service y se compilan aplicaciones de PHP en Linux, consulte la documentación de Oryx sobre cómo se detectan y se compilan las aplicaciones de PHP.

Personalización del inicio

Si desea, puede ejecutar un comando personalizado en el tiempo de inicio del contenedor. Para hacerlo, ejecute el siguiente comando en la instancia de Cloud Shell:

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

Acceso a variables de entorno

En App Service, puede establecer la configuración de la aplicación fuera del código de la aplicación. Luego podrá acceder a ellas mediante el patrón estándar de getenv(). Por ejemplo, para acceder a una configuración de una aplicación denominada DB_HOST, use el código siguiente:

getenv("DB_HOST")

Cambio de la raíz del sitio

La plataforma web que prefiera puede usar un subdirectorio como la raíz del sitio. Por ejemplo, Laravel usa el subdirectorio public/ como la raíz del sitio.

Para personalizar la raíz del sitio, establezca la ruta de acceso de la aplicación virtual para la aplicación mediante el comando az resource update. En el ejemplo siguiente se establece la raíz del sitio en el subdirectorio public/ del repositorio.

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

De manera predeterminada, Azure App Service apunta la ruta de acceso de la aplicación virtual raíz (/) al directorio raíz de los archivos de la aplicación implementada (sites\wwwroot).

La plataforma web que prefiera puede usar un subdirectorio como la raíz del sitio. Por ejemplo, Laravel usa el subdirectorio public/ como la raíz del sitio.

La imagen de PHP predeterminada para App Service usa Nginx y cambia la raíz del sitio al configurar el servidor Nginx con la directiva root. Este ejemplo de archivo de configuración contiene los siguientes fragmentos que cambian la directiva 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
    }
    ...

El contenedor predeterminado usa el archivo de configuración que se encuentra en /etc/nginx/sites-available/default. Tenga en cuenta que cualquier edición que realice en este archivo se borra cuando se reinicia la aplicación. Para realizar un cambio eficaz en los reinicios de la aplicación, agregue un comando de inicio personalizado, como este ejemplo:

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

Este comando reemplaza el archivo de configuración predeterminado de Nginx por un archivo denominado default en la raíz del repositorio y reinicia Nginx.

Detección de sesión de HTTPS

En App Service, la terminación de TLS/SSL se produce en los equilibradores de carga de red, por lo que todas las solicitudes HTTPS llegan a la aplicación como solicitudes HTTP sin cifrar. Si su aplicación lógica necesita comprobar si las solicitudes de usuario están cifradas, inspeccione el encabezado X-Forwarded-Proto.

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

Los marcos web más usados le permiten acceder a la información de X-Forwarded-* en el patrón de aplicación estándar. En CodeIgniter, is_https() comprueba el valor de X_FORWARDED_PROTO de forma predeterminada.

Personalización de la configuración de php.ini

Si necesita hacer cambios en su instalación de PHP, puede cambiar cualquiera de las directivas php.ini siguiendo estos pasos.

Nota

La mejor forma de ver la versión de PHP y la configuración de php.ini actual consiste en llamar a phpinfo() en la aplicación.

Personalización de las directivas que no son de PHP_INI_SYSTEM

Para personalizar las directivas PHP_INI_USER, PHP_INI_PERDIR y PHP_INI_ALL (consulte las directivas de php.ini), agregue un archivo .user.ini al directorio raíz de la aplicación.

Agregue la configuración al archivo .user.ini usando la misma sintaxis que usaría en un archivo php.ini. Por ejemplo, si quiere desactivar la configuración display_errors y establecer la configuración upload_max_filesize en 10 M, el archivo .user.ini contendría el texto siguiente:

 ; Example Settings
 display_errors=On
 upload_max_filesize=10M

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

Vuelva a implementar la aplicación con los cambios y reiníciela.

Como alternativa al uso del archivo .user.ini, puede usar ini_set() en la aplicación para personalizar estas directivas que no son de PHP_INI_SYSTEM.

Para personalizar las directivas PHP_INI_USER, PHP_INI_PERDIR y PHP_INI_ALL para aplicaciones web de linux, como upload_max_filesize y expose_php, use un archivo "ini" personalizado. Puede crearlo en una sesión SSH.

Vaya al sitio de KUDU https://<nombredelsitio>.scm.azurewebsites.net.
Seleccione Bash o SSH en el menú superior.
En Bash/SSH, vaya al directorio "/home/site/wwwroot".
Cree un directorio denominado "ini" (por ejemplo, mkdir ini).
Cambie el directorio de trabajo actual a la carpeta "ini" que acaba de crear.

Debe crear un archivo "ini" al que agregar la configuración. En este ejemplo, utilizamos "extensions.ini". No hay editores de archivos como Vi, Vim o Nano, así que usará echo para añadir la configuración al archivo. Cambie "upload_max_filesize" de 2 M a 50 M. Use el siguiente comando para agregar la configuración y crear un archivo "extensions.ini" si aún no existe uno.

/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>

Luego, vaya a Azure Portal y agregue una Configuración de aplicación para examinar el directorio "ini" que acaba de crear para aplicar el cambio de upload_max_filesize.

Vaya a Azure Portal y seleccione su recurso de aplicación PHP de Linux de App Service.
Seleccione Configuración de la aplicación de la aplicación.
En la sección Configuración de la aplicación, seleccione + Agregar nueva configuración.
Para el Nombre de la configuración de la aplicación, introduzca "PHP_INI_SCAN_DIR" y para el valor, introduzca "/home/site/wwwroot/ini".
Seleccione el botón Guardar.

Nota

Si recompiló una extensión PHP, como GD, siga los pasos descritos en Recompilación de extensiones PHP en Azure App Service: Agregar extensiones PHP

Personalización de las directivas de PHP_INI_SYSTEM

Para personalizar las directivas de PHP_INI_SYSTEM (consulte directivas de php.ini), use la configuración de aplicación PHP_INI_SCAN_DIR.

En primer lugar, ejecute el siguiente comando en Cloud Shell para agregar una configuración de aplicación llamada 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"

Vaya a la consola de Kudu (https://<app-name>.scm.azurewebsites.net/DebugConsole) y navegue a d:\home\site.

Cree un directorio en d:\home\site llamado ini, después cree un archivo .ini en el directorio d:\home\site\ini (por ejemplo, settings.ini) con las directivas que quiera personalizar. Utilice la misma sintaxis que usaría en un archivo php.ini.

Por ejemplo, para cambiar el valor de expose_php, ejecute los siguientes comandos:

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

Para que los cambios surtan efecto, reinicie la aplicación.

Para personalizar las directivas de PHP_INI_SYSTEM (consulte directivas de php.ini), no puede usar el enfoque .htaccess. App Service proporciona un mecanismo diferente mediante la configuración de la aplicación PHP_INI_SCAN_DIR.

En primer lugar, ejecute el siguiente comando en Cloud Shell para agregar una configuración de aplicación llamada 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 es el directorio predeterminado donde se encuentra php.ini. /home/site/ini es el directorio personalizado en el que agregará un archivo personalizado .ini. Separe los valores con un :.

Vaya a la sesión SSH web con el contenedor Linux (https://<app-name>.scm.azurewebsites.net/webssh/host).

Cree un directorio en /home/site llamado ini, después cree un archivo .ini en el directorio /home/site/ini (por ejemplo, settings.ini) con las directivas que quiera personalizar. Utilice la misma sintaxis que usaría en un archivo php.ini.

Sugerencia

En los contenedores Linux incorporados en App Service, /home se utiliza como almacenamiento compartido persistente.

Por ejemplo, para cambiar el valor de expose_php, ejecute los siguientes comandos:

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

Para que los cambios surtan efecto, reinicie la aplicación.

Habilitación de las extensiones de PHP

Las instalaciones de PHP integradas contienen las extensiones más usadas. Puede habilitar extensiones adicionales en la misma forma que personaliza las directivas de php.ini.

Nota

La mejor forma de ver la versión de PHP y la configuración de php.ini actual consiste en llamar a phpinfo() en la aplicación.

Para habilitar extensiones adicionales, siga los pasos que se detallan a continuación:

Agregue un directorio bin al directorio raíz de la aplicación y coloque los archivos de extensión .dll en él (por ejemplo, mongodb.dll). Asegúrese de que las extensiones sean compatibles con la versión de PHP en Azure y que sean compatibles con VC9 y no seguras para subprocesos (nts).

Implemente los cambios

Siga los pasos que se indican en Personalización de las directivas de PHP_INI_SYSTEM, agregue las extensiones al archivo custom.ini con las directivas extension o zend_extension.

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

Para que los cambios surtan efecto, reinicie la aplicación.

Las instalaciones de PHP integradas contienen las extensiones más usadas. Puede habilitar extensiones adicionales en la misma forma que personaliza las directivas de php.ini.

Nota

La mejor forma de ver la versión de PHP y la configuración de php.ini actual consiste en llamar a phpinfo() en la aplicación.

Para habilitar extensiones adicionales, siga los pasos que se detallan a continuación:

Agregue un directorio bin al directorio raíz de la aplicación y coloque los archivos de extensión .so en él (por ejemplo, mongodb.so). Asegúrese de que las extensiones sean compatibles con la versión de PHP en Azure y que sean compatibles con VC9 y no seguras para subprocesos (nts).

Implemente los cambios

Siga los pasos que se indican en Personalización de las directivas de PHP_INI_SYSTEM, agregue las extensiones al archivo custom.ini con las directivas extension o zend_extension.

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

Para que los cambios surtan efecto, reinicie la aplicación.

Acceso a los registros de diagnóstico

Use la utilidad error_log() estándar para que los registros de diagnóstico se muestren en Azure App Service.

Para acceder a los registros de la consola generados desde el código de la aplicación en App Service, active el registro de diagnósticos, para lo que debe ejecutar el siguiente comando en Cloud Shell:

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

Los valores posibles de --level son: Error, Warning, Info y Verbose. Todos los niveles incluyen el nivel anterior. Por ejemplo: Error incluye solo los mensajes de error, mientras que Verbose incluye todos los mensajes.

Una vez que se activa el registro de contenedor, ejecute el siguiente comando para ver la transmisión del registro:

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

Si no ve los registros de la consola de inmediato, vuelve a comprobarlo en 30 segundos.

Nota

También puede inspeccionar los archivos de registro desde el explorador en https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Para detener el streaming del registro en cualquier momento, escriba Ctrl+C.

Puede acceder a los registros de consola generados desde dentro del contenedor.

En primer lugar, active el registro de contenedores mediante la ejecución del siguiente comando:

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

Reemplace <app-name> y <resource-group-name> por los nombres adecuados para su aplicación web.

Una vez que se active el registro de contenedor, ejecute el siguiente comando para ver el flujo del registro:

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

Si no ve los registros de la consola de inmediato, vuelve a comprobarlo en 30 segundos.

Para detener el streaming de registro en cualquier momento, escriba Ctrl+C.

Los archivos de registro también se pueden inspeccionar en un explorador en https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Solución de problemas

Cuando una aplicación de PHP en funcionamiento se comporta de manera diferente en App Service o genera errores, intente lo siguiente:

Acceso a la secuencia de registros.
Pruebe la aplicación localmente en modo de producción. App Service ejecuta la aplicación en el modo de producción, por lo que deberá asegurarse de que el proyecto funciona según lo previsto en modo de producción localmente. Por ejemplo:
- En función de su archivo composer.json, pueden instalarse distintos paquetes para el modo de producción (require frente a require-dev).
- Algunas plataformas web pueden implementar archivos estáticos de forma diferente en modo de producción.
- Algunas plataformas web pueden usar scripts de inicio personalizados cuando se ejecutan en modo de producción.
Ejecute la aplicación en App Service en el modo de depuración. Por ejemplo, en Laravel, puede configurar la aplicación para que genere mensajes de depuración en producción al configurar el ajuste de la aplicación APP_DEBUG en true.

robots933456 en registros

Puede ver el mensaje siguiente en los registros del contenedor:

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

Puede omitir este mensaje sin problemas. /robots933456.txt es una ruta de acceso de la dirección URL ficticia que utiliza App Service para comprobar si el contenedor es capaz de atender las solicitudes. Una respuesta 404 simplemente indica que la ruta de acceso no existe, pero permite a App Service saber que el contenedor está en buen estado y listo para responder a las solicitudes.

Pasos siguientes

Tutorial: Aplicación de PHP con MySQL

P+F sobre App Service en Linux

O consulte estos recursos adicionales:

Variables de entorno y configuración de la aplicación en Azure App Service

Configuración de una aplicación de PHP para Azure App Service

Visualización de la versión de PHP

Establecer la versión de PHP

Ejecución de Composer

Ejecutar Grunt, Bower o Gulp

Bower

Gulp

Grunt

Personalización de la automatización de compilaciones

Personalización del inicio

Acceso a variables de entorno

Cambio de la raíz del sitio

Detección de sesión de HTTPS

Personalización de la configuración de php.ini

Personalización de las directivas que no son de PHP_INI_SYSTEM

Personalización de las directivas de PHP_INI_SYSTEM

Habilitación de las extensiones de PHP

Acceso a los registros de diagnóstico

Solución de problemas

robots933456 en registros

Pasos siguientes

Recursos adicionales