ベースイメージにalpineを使用したLaravelの開発環境にXdebug入れようとしたら少し詰まったのでその備忘録

XdebugなしでPHPの開発ができなくなってしまった人間です。

これまでDockerを使用したLaravelの開発環境ではベースイメージにphp:<version>-fpmやphp:<version>-alpineを使用してきたのですが、先日alpineをベースイメージに使用した環境を使用することがありました。
Xdebugを有効にするまでに少し詰まったので備忘録として残します。

環境

ベースイメージ alpine:3.14
Xdebug は 3
PHPは8

元々インストールしていたパッケージ

RUN apk --no-cache add \
  curl \
  nginx \
  php8 \
  php8-bcmath \
  php8-ctype \
  php8-curl \
  php8-dom \
  php8-fileinfo \
  php8-fpm \
  php8-gd \
  php8-intl \
  php8-json \
  php8-mbstring \
  php8-mysqli \
  php8-pdo_mysql \
  php8-opcache \
  php8-openssl \
  php8-phar \
  php8-session \
  php8-simplexml \
  php8-tokenizer \
  php8-xml \
  php8-xmlreader \
  php8-xmlwriter \
  php8-zlib \
  supervisor

手順

まず、Dockerfileに下記の記述を追加しました。

# こちらalpineを使用している場合に必要みたいです
RUN apk --no-cache add \
  autoconf gcc g++ make

RUN pecl install xdebug \
  && docker-php-ext-enable xdebug

ビルドすると

 => ERROR [6/8] RUN pecl install xdebug   && docker-php-ext-enable xdebug                                                                                                                                                           0.5s
------                                                                                                                                                                                                                                   
 > [6/8] RUN pecl install xdebug   && docker-php-ext-enable xdebug:                                                                                                                                                                      
#9 0.453 /bin/sh: pecl: not found                                                                                                                                                                                                        
------                      

pecl: not foundのエラーが出ました。

どうやらpeclを使用するためには php-pear php-devの2つのパッケージが必要みたいです。

下記を追加しました。

RUN apk --no-cache add \
   php8-pear \
   php8-dev \

ビルドすると

 => ERROR [6/8] RUN pecl install xdebug   && docker-php-ext-enable xdebug                                                                                                                                                           0.3s
------                                                                                                                                                                                                                                   
 > [6/8] RUN pecl install xdebug   && docker-php-ext-enable xdebug:
#9 0.262 /bin/sh: pecl: not found

pecl: not foundのエラーが出ました！

あれれ。。。

一旦RUN pecl install xdebug \ && docker-php-ext-enable xdebugをコメントアウトした状態でビルドを通し、Docker環境に入って様子を見ることにしました。
(ここを確認しようと思うまで少し時間がかかりました。。)

/usr/bin配下を確認

ls -l /usr/bin/

# 実行結果 一部抜粋
-rwxr-xr-x    1 root     root           799 Nov 18  2021 pear8
-rwxr-xr-x    1 root     root           820 Nov 18  2021 peardev8
-rwxr-xr-x    1 root     root           733 Nov 18  2021 pecl8

pecl が確かになかったのでpeclコマンドを実行する前に pecl8に対してシンボリックリンクをはるよう下記を追加しました。

RUN ln -s /usr/bin/pecl8 /usr/bin/pecl

ビルドすると、、、

#10 49.11 Build process completed successfully
#10 49.11 Installing '/usr/lib/php8/modules/xdebug.so'
#10 49.12 install ok: channel://pecl.php.net/xdebug-3.1.5
#10 49.12 configuration option "php_ini" is not set to php.ini location
#10 49.12 You should add "zend_extension=/usr/lib/php8/modules/xdebug.so" to php.ini
#10 49.15 /bin/sh: docker-php-ext-enable: not found
------
executor failed running [/bin/sh -c pecl install xdebug   && docker-php-ext-enable xdebug]: exit code: 127

エラーは出ているものの、pecl install xdebugは通っているみたいです！

docker-php-ext-enableコマンドはpeclでインストールしたパッケージを有効するのに使用しますが、このコマンドを使用しなくてもいいみたいです。

今回はとりあえずXdebugを動かしたかったので、docker-php-ext-enable xdebugをコメントアウトし、echoでphp.iniに各設定を書き込むようにしました。

RUN pecl install xdebug
  # コメントアウト
  # && docker-php-ext-enable xdebug
  
RUN echo "zend_extension=/usr/lib/php8/modules/xdebug.so" >> /etc/php8/php.ini
RUN { \
  echo '[xdebug]'; \
  echo 'xdebug.mode=debug'; \
  echo 'xdebug.start_with_request=yes'; \
  echo 'xdebug.client_host=host.docker.internal'; \
  echo 'xdebug.client_port=9003'; \
  echo 'xdebug.log=/tmp/xdebug.log'; \
  echo 'xdebug.log_level=0'; \
} >> /etc/php8/php.ini

ビルドが通りちゃんと入ったかを確認

/var/www/html $ php -v
PHP 8.0.13 (cli) (built: Nov 18 2021 23:50:23) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.13, Copyright (c) Zend Technologies
    with Xdebug v3.1.5, Copyright (c) 2002-2022, by Derick Rethans
    with Zend OPcache v8.0.13, Copyright (c), by Zend Technologies

＼(^o^)／

有効になっていることを確認できました。
これで安心して開発できそうです。

設定ファイル

最後にXdebugの設定内容とvscodeの設定ファイルの内容を残しておきます。

php.ini

zend_extension=/usr/lib/php8/modules/xdebug.so
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.log_level=0

.launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceRoot}"
      },
    },
  ]

参考

https://yutaro-blog.net/2021/07/08/laravel-docker-xdebug-vscode/

https://stackoverflow.com/questions/1625161/peclcommand-not-found

https://hub.docker.com/_/php

https://prograshi.com/language/php/pecl-install-docker-php-ext-install/