Deploying PHP apps

Zeabur supports not only traditional multi-file PHP apps with index.php as the entry point but also offers one-click deployment for frameworks like Laravel, ThinkPHP, CodeIgniter, etc.

NPM Support

If your project root contains a package.json, Zeabur will automatically install Node.js and NPM for you; if your package.json contains a build script, Zeabur will automatically run npm install && npm run build to build the artifacts.

If you need to change the build commands (e.g., to run npm run build:dist), please refer to the section on Customizing Build and Start Commands.

Customizing Build and Start Commands

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

"Build commands" are suitable for scenarios where you need to download or compile custom artifacts (such as CSS, JavaScript, etc.) or write constant configurations. For example, if you want to write settings to the /etc folder, you can set an environment variable like this:

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

Or add the following settings in zbpack.json:

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

You can also execute npm commands here. Note that Zeabur will only install Node.js and NPM if there is a package.json in the project root directory. If your project does not contain a package.json, npm commands will not be available:

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

"Start commands" are suitable for scenarios when you need to run command before starting a PHP server, such as adding php artisan migrate to the original command to migrate database. For example, you can set an environment variable like this:

ZBPACK_START_COMMAND="php artisan migrate && _startup"

Or add the following settings in zbpack.json:

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

Here, _startup is Zeabur's original start command (which can be found in the zbpack source code (opens in a new tab)). If you have a custom start_command, _startup must be included in your start command; otherwise, the PHP server will not start.

Both build_command and start_command will be executed using a POSIX-compliant shell, so you can use && to chain multiple commands, or use ; to separate multiple commands.

Custom PHP Version

Zeabur defaults to using PHP 8, but you can specify the PHP version using composer.json or zbpack settings. If your project uses Laravel Sail, Zeabur will also automatically detect the version based on docker-compose.yml. zbpack settings have the highest priority, followed by composer.json, and then Laravel Sail.

`composer.json`

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

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

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

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

In the example above, 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 by Laravel Sail in docker-compose.yml.

Laravel Sail Docker Compose definition

zbpack Settings

If you are not using Laravel Sail or Composer but need to change the PHP version, you can use the ZBPACK_PHP_VERSION environment variable

ZBPACK_PHP_VERSION=8.0

Or add the following setting in zbpack.json

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

to customize the PHP version.

Customizing `php.ini` Settings

Use Zeabur's config file editor to create a configuration file under /usr/local/etc/php/conf.d with the extension ini. You can directly write the PHP settings you wish to override in this file.

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

upload_max_filesize = 100M

Customizing NGINX Configuration

Use Zeabur's config file editor to create a configuration file at the path /etc/nginx/sites-enabled/default, which overrides the default NGINX configuration on Zeabur.

If you'd like to tweak the NGINX configuration based on the existing configuration, you can download the current NGINX configuration file used by Zeabur from the zbpack NGINX configuration repository (opens in a new tab), and make your modifications on that basis. For example, if you wish to disable gzip compression, you can change the template's gzip_static on; to gzip_static off;.

server {
    # see https://github.com/zeabur/zbpack/blob/main/internal/php/nginx-conf/default.conf

    location / {
        try_files $uri $uri/ /index.php?$query_string;
        gzip_static off;  // disable gzip compression
	}
}

Spring Boot Laravel