How do I configure xDebug in PHP using Docker containers?

After a lot of trial and error I have now solved this myself. Just writing here in the hope that this might help someone else, also for future reference for myself when I inevietably forget!

This works for a Dockerized Laravel app using PHP 8.1.8 with XDebug 3.1.5.

In my local project I have my xDebug options in php/php-dev.ini:

zend_extension=xdebug
xdebug.client_port = 9009
xdebug.idekey = PHPSTORM
xdebug.mode = develop,debug
xdebug.client_host = host.docker.internal

My docker-compose.yml files looks like this:

version: '3.8'
services:
  nginx:
    build:
      context: .
      dockerfile: nginx.dockerfile
    ports:
      - 80:80
    volumes:
      - ./src:/var/www/html
    depends_on:
      - mysql
      - php
  mysql:
    image: mariadb:10.5
    ports:
      - 3306:3306
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_USER: laravel
      MYSQL_PASSWORD: secret
      MYSQL_ROOT_PASSWORD: secret
    volumes:
      - ./mysql:/var/lib/mysql
  php:
    build:
      context: .
      dockerfile: php.dockerfile
    volumes:
      - ./src:/var/www/html
      - ./php/php-dev.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
  composer:
    build:
      context: .
      dockerfile: composer.dockerfile
    volumes:
      - ./src:/var/www/html
    working_dir: /var/www/html
  npm:
    image: node:current-alpine
    volumes:
      - ./src:/var/www/html
    entrypoint: ["npm"]
    working_dir: /var/www/html
  artisan:
    build:
      context: .
      dockerfile: php.dockerfile
    volumes:
      - ./src:/var/www/html
    working_dir: /var/www.html
    depends_on:
      - mysql
    entrypoint: ["php", "/var/www/html/artisan"]

My php.dockerfile is this:

FROM php:8-fpm-alpine
ENV PHPGROUP=laravel
ENV PHPUSER=laravel
RUN adduser -g ${PHPGROUP} -s /bin/sh -D ${PHPUSER}
RUN sed -i "s/user = www-data/user = ${PHPUSER}/g" /usr/local/etc/php-fpm.d/www.conf
RUN sed -i "s/group = www-data/group = ${PHPGROUP}/g" /usr/local/etc/php-fpm.d/www.conf
RUN mkdir -p /var/www/html/public
RUN docker-php-ext-install pdo pdo_mysql
RUN apk add --no-cache $PHPIZE_DEPS \
    && pecl install xdebug \
    && docker-php-ext-enable xdebug
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer
CMD ["php-fpm", "-y", "/usr/local/etc/php-fpm.conf", "-R"]

In PHPStorm my PHP - Debug settings are:

My PHP - Debug - DBGg Proxy:

Under PHP - Servers, there is a server with a name of _ this seems to have been created automatically! Not sure how that works but in there the settings are as follows:

Then under mappings I simply mapped the src folder in my local project to the /var/www/html folder on the container.