Customizing Laravel Vapor: Extensions, Binaries, and PHP Runtime

Overview

Laravel Vapor
offers a robust serverless experience, but default environments often lack the specific tools required for media processing or specialized arithmetic. By leveraging Docker-based deployments, we can step beyond the standard runtime limitations. This tutorial demonstrates how to modify your Dockerfile to inject custom binaries like
FFmpeg
, install specialized
PHP
 extensions, and override core configuration settings.

Prerequisites

To follow along, you should be familiar with:

  • Basic
    Docker
     concepts (images, layers, and containers).
  • PHP
     development and extension management.
  • Laravel Vapor
     deployment workflows.
  • Alpine Linux
     package management (apk).

Key Libraries & Tools

  • Alpine Linux
    : The lightweight security-oriented distribution used as the base for Vapor images.
  • FFmpeg
    : A complete solution to record, convert, and stream audio and video.
  • MySQL
    : Command-line utilities for interacting with MySQL databases.
  • GMP Extension: The GNU Multiple Precision library for working with arbitrary-length integers in PHP.

Installing System Binaries

Since Vapor’s Docker images use

Alpine Linux
, we use the apk package manager. If your application needs to process video or connect to databases via the CLI, you must add these to your Dockerfile manually.

RUN apk --update add \
    ffmpeg \
    mysql-client

Always include the --update flag to ensure you are pulling the latest metadata from the Alpine repositories before the installation begins.

Compiling PHP Extensions

PHP extensions like gmp often require underlying system headers. If you attempt to install an extension without its dependency, the build will fail during the compilation phase. To fix this, install the development library (-dev) before running the helper script.

# Install the system dependency first
RUN apk add --no-cache gmp-dev

# Use the helper to compile and enable the extension
RUN docker-php-ext-install gmp

Customizing php.ini Overrides

Sometimes you need to increase max_input_vars or adjust memory limits. Instead of modifying the base image, create a local php.ini and copy it into the specific directory where PHP scans for additional configurations.

COPY php.ini /usr/local/etc/php/conf.d/overrides.ini

Syntax Notes & Best Practices

  • Layer Optimization: Combine multiple apk add commands into a single RUN instruction to keep image sizes small.
  • No-Cache: Use apk add --no-cache to avoid storing the package index locally, further reducing the image footprint.
  • Location Matters: In Vapor images, the configuration directory is strictly located at /usr/local/etc/php/conf.d/.

Tips & Gotchas

  • Compilation Failures: If docker-php-ext-install fails, check the logs for missing .h files. This usually indicates a missing -dev package in Alpine.
  • Deployment Sync: Remember that changes to the Dockerfile require a fresh vapor deploy to rebuild the image and propagate changes to the cloud environment.
3 min read