Skip to content

php.md

Latest commit

聽

History

History
242 lines (151 loc) 路 9.18 KB

php.md

File metadata and controls

242 lines (151 loc) 路 9.18 KB
Raw

PHP

We use the official PHP Docker images and add a few extra features to make them nicer for everyday use.

Installation

PHP 8.5 is the default service and is included in the base docker-compose.yml configuration.

Other PHP versions are optional and are not installed or enabled by default. To enable an additional version, add its corresponding YAML file to the COMPOSE_FILE list in .env. For example, to enable PHP 7.4 for a legacy project on Unix systems (including WSL; use semicolons instead of colons on non-WSL Windows):

COMPOSE_FILE=docker-compose.yml:opt/php74.yml

After updating the .env file, run docker compose up -d --remove-orphans to start the service.

Which versions are available?

We provide PHP 5.6, 7.x, and 8.x. PHP 8.5 is the default stable version.

See the /php and /php/src folders for more details.

How do I use a specific version?

If you're happy with the default version of PHP 8.5 then you simply:

  • Use https://<folder>.localhost in your browser
  • Use devin 85 to jump into the 8.5 container and run PHP commands (eg. composer, artisan)

There are two extra steps if you want a different version of PHP. Let's assume you want PHP 7.4:

  1. Add the PHP version to the COMPOSE_FILE list in .env
  • eg. COMPOSE_FILE=docker-compose.yml:opt/php74.yml
  1. Update your Docker containers: docker compose up -d --remove-orphans

Now use https://<folder>.php74.localhost in your browser or devin 74 in your terminal.

You can enable as many versions of PHP as you like, but note that starting or updating the containers will take a little longer.

Why is <xyz tool> missing?

Only the latest version of PHP has these tools installed:

  • Node.js (latest LTS) & NPM (latest)
  • PHPCS (with Wordpress code standards added)
  • Wordpress CLI
  • ZSH

All other PHP containers will only have Composer installed.

This was a deliberate decision in order to keep the PHP containers as small as possible, but still provide the convenience of having these tools available.

If you want to install your own tools then see "How can I customise my containers?" in the General FAQ.

How do I run CRONs?

Each version of PHP can have it's own scheduled CRON jobs.

  1. Create a file called custom_crontab in the PHP folder of your choice (eg. php/85/custom_crontab).
  2. Add your scheduled commands into custom_crontab
  3. Rebuild that PHP image (eg. for PHP 8.5): docker compose build php85-fpm
  4. Use the new image: docker compose up -d

Your CRON entries should look something like this:

* * * * * cd /var/www/html/my-laravel-site/ && php artisan schedule:run >> /dev/null 2>&1

CRONs will only run while your Docker Dev containers are running.

How do I get BrowserSync working from inside a container?

BrowserSync works by proxying a host and auto-refreshing the browser when a file was updated. When run from within a container, it needs to proxy the PHP site through the apache container (to get the same result that you see).

We have 2 options for this.

1. Adjust your site's config

We have a (wildcard) DNS redirect setup at *.lde.pvtl.io which points to the apache container's IP address. This is for convenience, so that our docker container can use that hostname to find the IP. Simply adjust your BrowserSync config to use this hostname:

  1. BrowserSync config: Instead of using the hostname <folder>.pub.localhost, use <folder>.pub.lde.pvtl.io
  2. (optional) .env: Adjust your site's hostname (usually in .env) to use the same .lde.pvtl.io alternative
    • Primarily relevant in Wordpress sites, because Wordpress will redirect to WP_HOME

2. Adjust the hosts file (inside the container)

Follow the instructions in the section below (HTTP requests from one LDE site to another).

HTTP requests from one LDE site to another

By default, you cannot send cURL, Wget or other HTTP requests from one site in your LDE to another (or itself). The PHP containers (where the HTTP requests are sent from) don't know which IP to use for https://<folder>.localhost.

You can work around this issue by editing the hosts file inside the PHP container which is sending the request, and manually tell it the IP to use.

Note, we always use the IP address of the apache container since it handles all HTTP requests.

  1. Exec into the PHP container (the source of the HTTP request): docker compose exec php85-fpm bash
  2. Find the IP address of the apache container: ping -c 1 apache | awk -F '[()]' '{print $2}' | head -n 1
  3. Edit the hosts file: nano /etc/hosts
  4. Append to the end 192.168.103.100 wp.pub.localhost (adjust the destination hostname to suit)

Customising PHP (.ini)

  1. Add your settings into php/conf/custom.ini
  2. Rebuild and restart all containers docker compose up -d --build.

Your config changes will take effect in all PHP containers.

Installing PHP extensions

Need to connect to Microsoft SQL Server? Read the next FAQ.

A great selection of extensions are pre-installed, but you can add your own too.

We are using the official PHP Docker images and they include a script which assists with installing and enabling PHP extensions.

Here's how you could install the "sockets" extension:

devin 85
sudo -E docker-php-ext-install sockets
exit
docker compose restart

Or here is how you can install a PIE extension (for PHP 8.1+):

devin 85
sudo -E pie install swoole/swoole
exit
docker compose restart

For older PHP versions (8.0 and below), you can still use PECL. Choose an extension release compatible with your PHP version; this example is for PHP 8.0:

devin 80
sudo -E pecl install -f swoole-5.1.3
sudo -E docker-php-ext-enable swoole
exit
docker compose restart

Your extensions will need to be re-installed after you rebuild or upgrade your Docker containers. If you want your changes to persist, consider using the "custom_scripts" feature (see the General FAQ).

Some extensions (like ImageMagick) depend on operating system packages.

devin 85
sudo apt-get update
sudo apt-get install libmagickwand-dev imagemagick
sudo -E pie install imagick/imagick
exit
docker compose restart

If you're ever unsure which path ImageMagick has been installed into, run whereis convert. It should return something like convert: /usr/bin/convert.

Connecting to Microsoft SQL Server

You will need to install the PHP extensions for Microsoft SQL Server before attempting to connect.

Your extensions will need to be re-installed after you rebuild or upgrade your Docker containers. If you want your changes to persist, consider using the "custom_scripts" feature (see the General FAQ).

Note: Uses Debian Bookworm (12.x) repo even though we're running Debian Trixie (13.x). We're waiting for Microsoft to publish the required packages for Trixie. It's a little weird, but it works.

Step 1: Switch to root

sudo su

Step 2: Install dependencies

Note: Trixie ships with the new 2025 version of Microsoft's signing key, but we intentionally downgrade it to use the old Bookworm (12.x) repo. We can clean this up when packages for Trixie become available.

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
  && curl https://packages.microsoft.com/config/debian/12/prod.list | tee /etc/apt/sources.list.d/mssql-release.list \
  && apt update \
  && ACCEPT_EULA=Y apt-get install -y unixodbc-dev msodbcsql18 mssql-tools18

Step 3: Install extensions

pecl install sqlsrv pdo_sqlsrv

Step 4: Exit root

exit

Step 5: Enable extensions

sudo -E docker-php-ext-enable sqlsrv pdo_sqlsrv

Step 6: Test

php -m | grep sqlsrv

Using Valkey as a session handler

Did you know that PHP sessions will block concurrent requests (for the same session) until the first request is finished? This is done to prevent race conditions when writing to the session file.

You can improve your concurrency performance (at the risk of race conditions) by using Valkey as your session handler.

  1. Enable the Valkey service by adding opt/valkey.yml to the COMPOSE_FILE list in .env
  2. Create a php/conf/custom.ini file (if it doesn't already exist)
  3. Append the following lines
[PHP]
session.save_handler = valkey
session.save_path = "tcp://valkey:6379"
  1. Rebuild docker compose up -d --build

How do I change the default version of PHP?

The default version of PHP is typically the latest stable version.

But perhaps you want to use PHP 7.4 for all URLs which do not specify a PHP version (like <folder>.localhost and <folder>.pub.localhost).

  1. Add opt/php74.yml to the COMPOSE_FILE list in .env and run docker compose up -d --remove-orphans.
  2. In both apache/sites/localhost/zzz-default.conf and apache/sites/pub.localhost/zzz-default.conf, replace php85-fpm:9000 with php74-fpm:9000 in each SetHandler directive. Update both the HTTP and HTTPS virtual hosts in each file.
  3. Restart Apache to reload these bind-mounted configuration files: docker compose restart apache.