Deploying PHP apps

Zeabur supports not only traditional multi-file PHP application with index.php as the entry point but also one-click deployment of frameworks such as Laravel, Symfony, ThinkPHP, and CodeIgniter.

PHP Environment

Zeabur uses the latest version of PHP 8 by default and an NGINX + php-fpm server to run your code.

The PHP environment in Zeabur comes with built-in Composer and PHP extensions like apcu, bcmath, gd, intl, mysqli, opcache, pcntl, pdo_mysql, sysvsem, and zip. If your composer.json includes other ext- prefixed extension definitions, Zeabur will automatically install the corresponding extensions. Additionally, tools like Node.js, Crontab, cURL, gettext, Git, grep, pkg-config, and unzip are pre-installed.

By default, Zeabur provides the environment variables APP_ENV=prod and APP_DEBUG=true to your application. You can manually override these variables in the “Environment Variables” section of the Zeabur console.

For the complete base image configuration, check out the zbpack code repository.

NPM Support

If your project has a package.json file, Zeabur will automatically run npm install to install dependencies.

If your package.json contains a build script, Zeabur will also run npm run build to generate build artifacts.

Custom Build and Start Commands

Zeabur allows you to customize the build and start commands for PHP using environment variables or configuration files.

Build Command

The “build command” is ideal for scenarios where you need to download or compile custom artifacts (e.g., CSS, JavaScript) or configure settings. For instance, to write a configuration file to the /etc directory, you can set an environment variable:

ZBPACK_BUILD_COMMAND=echo 'your-configuration' > /etc/somewhere

Or, you can add the following in zbpack.json:

{
    "build_command": "echo 'your-configuration' > /etc/somewhere"
}

You can also run additional npm commands here:

{
    "build_command": "npm run build:dist"
}

The build command will not interfere with Zeabur’s default build process, so there’s no need to repeat commands that Zeabur already handles.

Start Command

The “start command” is suitable for situations where you want to execute commands while starting the PHP server, such as running php artisan migrate to create database tables. For example, you can set an environment variable:

ZBPACK_START_COMMAND="php artisan migrate && _startup"

Or add the following in zbpack.json:

{
    "start_command": "php artisan migrate && _startup"
}

For continuously running services, the startup command should be enclosed in () and joined with &:

ZBPACK_START_COMMAND="(php artisan reverb:start &); _startup"

Or:

{
    "start_command": "(php artisan reverb:start &); _startup"
}

Here, _startup is Zeabur’s default startup command (refer to zbpack). If you customize the start_command, you must include _startup in the command; otherwise, the PHP server will not start.

Both build_command and start_command are executed using a POSIX-compatible shell, so you can chain multiple commands with && or separate them with ;.

Custom PHP Version

Zeabur uses PHP 8 by default, but you can specify the PHP version through composer.json or zbpack configuration. If your project uses Laravel Sail, Zeabur can automatically detect the PHP version from docker-compose.yml. The priority order is: zbpack configuration > composer.json > Laravel Sail.

composer.json

Set the PHP version range in the require section of composer.json:

{
    "require": {
        "php": "7.4"
    }
}

In this example, Zeabur will use the latest patch version of PHP 7.4 to run your project.

{
    "require": {
        "php": "^7.4"
    }
}

Here, Zeabur will use the latest minor version of PHP 7 to run your project.

Laravel Sail

If your project uses Laravel Sail, Zeabur will automatically detect and use the PHP version defined in the docker-compose.yml file.

zbpack Configuration

If you’re not using Laravel Sail or Composer but need to specify a PHP version, you can use the ZBPACK_PHP_VERSION environment variable:

ZBPACK_PHP_VERSION=8.0

Or add the following in zbpack.json:

{
    "php": {
        "version": "8.0"
    }
}

Custom php.ini Settings

Using Zeabur’s configuration file editor, create a configuration file in the /usr/local/etc/php/conf.d directory with the .ini extension and include the PHP settings you want to override.

For example, to set the maximum upload file size to 100MB, create a file /usr/local/etc/php/conf.d/upload.ini with the following content:

upload_max_filesize = 100M

Custom NGINX Configuration

Using Zeabur’s configuration file editor, create a configuration file at /etc/nginx/sites-enabled/default to override the default NGINX settings in Zeabur. The editor will prefill the current NGINX configuration, which you can modify as needed.

For instance, to disable gzip compression, change gzip_static on; to gzip_static off; in the template.

location / {
    try_files $uri $uri/ /index.php$is_args$args;
    gzip_static off;
}