Laravel

Qué detecta Zenavo

Un repositorio con composer.json (o index.php) se compila con zbpack como PHP, y laravel/framework en composer.json lo marca como Laravel. La imagen es la oficial php:<version>-fpm con nginx delante, escuchando en el puerto 8080:

Paso	Qué ocurre
Versión de PHP	ZBPACK_PHP_VERSION; si no, el runtime de Laravel Sail en docker-compose.yml; si no, require.php en composer.json; 8 si no hay ninguno
Extensiones	apcu, bcmath, gd, intl, mysqli, opcache, pcntl, pdo_mysql, sysvsem y zip, más cada ext-* de composer.json (añade "ext-pdo_pgsql": "*" para PostgreSQL)
Instalar	composer install --optimize-autoloader --classmap-authoritative --no-dev, y npm install si hay un package.json (Node.js 22)
Optimizar	php artisan optimize, config:cache, event:cache, route:cache, view:cache, y luego npm run build si package.json tiene un script build
Servir	nginx sirve public/ y pasa el PHP a php-fpm

Ajustes para Laravel

El paso de optimización se ejecuta durante la compilación, y las compilaciones no reciben las variables del servicio (Plan de compilación). config:cache guardaría una configuración sin tu base de datos ni tu APP_KEY, y Laravel ignoraría después las variables en ejecución. Desactiva la optimización en la compilación y ejecútala al arrancar el servicio. En Settings → Build → zbpack options:

ZBPACK_PHP_OPTIMIZE=false
ZBPACK_BUILD_COMMAND=npm run build
ZBPACK_START_COMMAND=php artisan migrate --force && php artisan optimize && _startup

• ZBPACK_BUILD_COMMAND compila los recursos de Vite, que si no habría compilado el paso de optimización. Omítelo si la aplicación no tiene compilación de front-end.
• _startup arranca nginx y php-fpm; debe ir al final. php artisan optimize guarda en caché la configuración, las rutas, los eventos y las vistas con las variables del servicio, y las migraciones se ejecutan antes de que la aplicación empiece a servir, porque la compilación no llega a la base de datos.

Variables

En la pestaña Variable del servicio:

APP_KEY=base64:…
APP_ENV=production
APP_DEBUG=false
APP_URL=${ZENAVO_WEB_URL}
LOG_CHANNEL=stderr
DB_CONNECTION=pgsql
DB_URL=${POSTGRESQL_CONNECTION_STRING}

• Crea APP_KEY una vez con php artisan key:generate --show en tu ordenador, y consérvala: cambiarla cierra la sesión de todo el mundo y deja ilegibles los datos cifrados.
• LOG_CHANNEL=stderr envía los registros de Laravel a Runtime Logs en lugar de a archivos del contenedor, que se pierden en cada despliegue.
• APP_URL usa el dominio del puerto llamado web; usa el nombre que aparece en la pestaña Networking.
• Para MySQL, usa DB_CONNECTION=mysql y DB_URL=${MYSQL_CONNECTION_STRING}. Laravel lee DB_URL desde la versión 11; las anteriores usan DATABASE_URL.
• Redis para caché, sesiones y colas: REDIS_URL=${REDIS_CONNECTION_STRING}, CACHE_STORE=redis, SESSION_DRIVER=redis.

Desplegar

1. Añade PostgreSQL (o MySQL) al proyecto (Bases de datos).
2. Add Service → GitHub, elige el repositorio y la rama, añade las variables de arriba y haz clic en Next.
3. Comprueba que la vista previa muestra php y haz clic en Deploy. Define las opciones de zbpack de arriba en Settings → Build y vuelve a desplegar.
4. Genera un dominio o asocia el tuyo en la pestaña Networking.

Archivos y colas

• Las subidas en storage/app se pierden en cada despliegue. Guárdalas en un almacenamiento compatible con S3 (FILESYSTEM_DISK=s3 con las variables AWS_*).
• Los workers de colas y el planificador se ejecutan como servicios aparte del mismo repositorio: añade el repositorio otra vez con el comando de arranque php artisan queue:work (o php artisan schedule:work) en ZBPACK_START_COMMAND, y sin puerto HTTP.

Problemas habituales

Síntoma	Causa
No application encryption key has been specified	Falta APP_KEY, o la configuración se guardó en caché durante la compilación. Define APP_KEY y ZBPACK_PHP_OPTIMIZE=false.
La aplicación usa SQLite o localhost en vez de la base de datos	La configuración se guardó en caché durante la compilación, sin las variables. Define ZBPACK_PHP_OPTIMIZE=false y ejecuta php artisan optimize al arrancar.
could not find driver	Falta la extensión PDO. Añade "ext-pdo_pgsql": "*" a require en composer.json.
CSS y JavaScript devuelven 404	No se ejecutó la compilación de Vite. Define ZBPACK_BUILD_COMMAND=npm run build.
Los enlaces y redirecciones usan http://	Laravel no confía en el proxy que tiene delante. Confía en él en bootstrap/app.php con $middleware->trustProxies(at: '*').