Docs menu

Customizing the build

Customize the PHP build on Primcloud: Composer scripts, PHP extensions, web server config, and system packages.

On this page

Most PHP apps need no custom build steps. When yours does, use Composer's post-install-cmd script, settings and web server config files in your repo, or system packages declared in project.toml.

Build hooks#

Add build steps to the post-install-cmd script in composer.json. Composer runs it at the end of composer install:

composer.json
{
  "scripts": {
    "post-install-cmd": ["php scripts/generate-sitemap.php"]
  }
}

The commands run in order, and a non-zero exit fails the build. Your secrets are available to every command. Composer also runs post-install-cmd when you run composer install locally.

Don't cache configuration here. A cached config keeps the secret values from build time, and saving a secret redeploys without rebuilding. Cache it when your web process starts instead; see Deploying Laravel.

There's no hook for work that has to run before composer install.

JavaScript assets. A PHP app with a package.json at the root, like a Laravel or Symfony app that builds assets with Vite, also gets its JavaScript dependencies installed and built. That happens after composer install, so vendor/ is in place when your asset build scans it. The lockfile you commit picks the package manager:

Lockfile Asset build
package-lock.json, yarn.lock, or pnpm-lock.yaml Node.js is installed and dependencies are installed with npm, Yarn, or pnpm. See Node.js package managers.
bun.lock or bun.lockb Bun is installed, without Node.js, and dependencies are installed with bun install --frozen-lockfile. See Bun package managers.

Either way, the build script in package.json runs after the install, along with heroku-prebuild and heroku-postbuild when you define them. Put vite build there, not in post-install-cmd, which runs before your JavaScript dependencies are installed. A web line in your Procfile decides the web process. Without a Procfile, a start script in package.json, or a root server.js or index.js (with Bun, also server.ts or index.ts), becomes the web process in place of the PHP web server. Add a Procfile to keep PHP serving.

Custom install steps#

PHP settings. Put per-directory PHP settings in a .user.ini at your document root:

public/.user.ini
memory_limit = 512M
upload_max_filesize = 20M
post_max_size = 20M
max_execution_time = 60

Custom web server configuration. Both heroku-php-apache2 and heroku-php-nginx accept a config file path via -C:

Procfile
web: heroku-php-nginx -C nginx-server.conf public/

The file is included inside the server block, so it holds location blocks, rewrite rules, headers, and the like. Don't write a full nginx.conf: listening on $PORT and connecting to PHP-FPM are already handled.

The same shape works for Apache:

Procfile
web: heroku-php-apache2 -C apache-app.conf public/

Native dependencies#

Two shapes of "native" your PHP app can rely on:

PHP extensions with native code. Extensions like ext-redis, ext-imagick, ext-mongodb, and ext-grpc link against system libraries but are distributed as PHP extensions the build knows how to install. Declare them in composer.json:

composer.json
{
  "require": {
    "php": "^8.4",
    "ext-redis": "*",
    "ext-imagick": "*",
    "ext-mongodb": "*"
  }
}

Run composer update to record them in composer.lock, then commit and push. The build installs each one with PHP, and they're loaded automatically.

The Primcloud Runtime includes the standard PHP extensions and common third-party ones such as redis, imagick, mongodb, amqp, grpc, memcached, apcu, newrelic, and phalcon. The build log shows the version of each extension it installs.

System libraries and tools, like a program your code shells out to, are declared in project.toml, covered next.

Debian packages#

When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.deb-packages]
install = [
  "ghostscript",
  "libreoffice",
  "poppler-utils",
]

Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.

Advanced options (rarely needed):

  • Skip a package's dependencies: { name = "some-package", skip_dependencies = true }
  • Force a reinstall: { name = "some-package", force = true }
  • Install from a URL: download = ["https://example.com/package-1.2.3.deb"]
  • Add a package repository: a [[com.heroku.buildpacks.deb-packages.sources]] table with uri, suites, components, arch, and signed_by (the repository's key as an ASCII-armored PGP block).

Note

The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.