使用 PhpStorm 來開發和 Debug Laravel Sail 專案

微波爐發表於2022-01-17
PHPORMLaravelAI

Laravel Sail 是為 Laravel 提供的基於 Docker 的開發環境，可同時搭建包含 PHP、MySQL、Redis，XDebug 在內的開發環境，優勢：

  • 降低開發環境的搭建難度
  • 將對主機已有環境的影響降至最低
  • 統一團隊開發環境

在 WSL 內使用指令：

curl -s https://laravel.build/<專案名稱> | bash

執行後，將在當前目錄下建立一個 <專案名稱> 的資料夾，並在裡面構建一個 Laravel Sail 專案。

成功建立 Laravel 專案後，我們透過 cd 指令進入專案目錄

cd <專案名稱>

安裝 Laravel Sail 後，不要馬上按照提示執行 vendor/bin/sail up，還需要針對國內網路環境對 Dockerfile 進行調整，也就是將其中 Composer 等包管理工具的包來源修改為國內映象網站。

Laravel Sail 支援使用者自定義 Dockerfile 檔案，只需使用以下指令釋出 Dockerfile 檔案即可

php artisan sail:publish

釋出後，可在專案根目錄的 docker 資料夾中找到對應的 Dockerfile，共有三個版本，具體是哪個版本可開啟專案根目錄的 docker-compose.yml 檢視。

# For more information: https://learnku.com/docs/laravel/sail
version: '3'
services:
    laravel.test:
        build:
            # 此處即為執行的 Dockerfile 所在的資料夾
            context: ./docker/8.1
            # 此處為 Dockerfile 的檔名
            dockerfile: Dockerfile
            # 此處記錄 Dockerfile 的引數，${var} 表示 .env 檔案中 var 對應的值
            args:
                WWWGROUP: '${WWWGROUP}'

這裡我們使用的是 8.1 版本，開啟 ./docker/8.1/Dockerfile將其中的內容替換為：
Dockerfile 

FROM ubuntu:21.10

LABEL maintainer="Taylor Otwell"

ARG WWWGROUP
ARG NODE_VERSION=16

WORKDIR /var/www/html

ENV DEBIAN_FRONTEND noninteractive
ENV TZ=Asia/Shanghai
ENV APT_MIRROR http://mirrors.ustc.edu.cn

RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

RUN echo 'APT::Acquire::Retries "5";' > /etc/apt/apt.conf.d/80-retries \
  && sed -i "s|http://archive.ubuntu.com|$APT_MIRROR|g; s|http://security.ubuntu.com|$APT_MIRROR|g" /etc/apt/sources.list \
  && sed -i "s|http://ports.ubuntu.com|$APT_MIRROR|g" /etc/apt/sources.list \
  && apt-get update

RUN apt-get update \
    && apt-get install -y gnupg gosu curl ca-certificates zip unzip git supervisor sqlite3 libcap2-bin libpng-dev python2 \
    && mkdir -p ~/.gnupg \
    && chmod 600 ~/.gnupg \
    && echo "disable-ipv6" >> ~/.gnupg/dirmngr.conf \
    && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E5267A6C \
    && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C300EE8C \
    && echo "deb https://launchpad.proxy.ustclug.org/ondrej/php/ubuntu impish main" > /etc/apt/sources.list.d/ppa_ondrej_php.list \
    && apt-get update \
    && apt-get install -y php8.1-cli php8.1-dev \
       php8.1-pgsql php8.1-sqlite3 php8.1-gd \
       php8.1-curl \
       php8.1-imap php8.1-mysql php8.1-mbstring \
       php8.1-xml php8.1-zip php8.1-bcmath php8.1-soap \
       php8.1-intl php8.1-readline \
       php8.1-ldap \
       php8.1-msgpack php8.1-igbinary php8.1-redis php8.1-swoole \
       php8.1-memcached php8.1-pcov php8.1-xdebug \
    && php -r "readfile('https://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \
    && curl -sL https://deb.nodesource.com/setup_$NODE_VERSION.x | bash - \
    && apt-get install -y nodejs \
    && npm install -g npm \
    # npm 映象
    && npm config set registry https://registry.npm.taobao.org \
    && curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
    && echo "deb https://dl.yarnpkg.com/debian/ stable main" > /etc/apt/sources.list.d/yarn.list \
    && apt-get update \
    && apt-get install -y yarn \
    # Yarn 映象
    && yarn config set registry https://registry.npm.taobao.org \
    && apt-get install -y mysql-client \
    && apt-get install -y postgresql-client \
    && apt-get -y autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

RUN setcap "cap_net_bind_service=+ep" /usr/bin/php8.1

RUN groupadd --force -g $WWWGROUP sail
RUN useradd -ms /bin/bash --no-user-group -g $WWWGROUP -u 1337 sail

COPY start-container /usr/local/bin/start-container
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY php.ini /etc/php/8.1/cli/conf.d/99-sail.ini
RUN chmod +x /usr/local/bin/start-container

EXPOSE 8000

ENTRYPOINT ["start-container"]

修改後，即可啟動容器 

vendor/bin/sail up

若容器尚未構建的話，該指令會自動構建容器後啟動。也可以使用 -d 引數使其在後臺執行。

vendor/bin/sail up -d

啟動後可以檢視我們容器內的 PHP 版本

vendor/bin/sail php -v

使用 PhpStorm 來開發和 Debug Laravel Sail 專案
可以透過下面的指令來停止在後臺執行的 Sail 容器

vendor/bin/sail stop

如果在此前你已經構建過容器且希望重新構建一個，可以使用以下命令重新構建：

vendor/bin/sail build --no-cache

成功啟動容器後，使用主機訪問 localhost 即可看到 Laravel 的初始介面

image-20220117172609892

如果出現 Permission Denied 的情況，請賦予專案目錄 777 許可權，在專案目錄根目錄下執行

sudo chmod 777 ./ -R

File >> Open 在子系統的目錄中選擇我們的專案

使用 PhpStorm 來開發和 Debug Laravel Sail 專案

開啟專案後，可以直接在 Terminal 中執行需要在子系統中執行的指令，從而擺脫來回切換 PhpStorm 和 Windows Terminal 的麻煩。
image-20220117173041327

將專案目錄及內其內的檔案許可權修改為 777，方便使用 PhpStorm 進行編輯。

sudo chmod 777 ./ -R

這樣之後就可以關閉獨立的 WSL 視窗了，直接在 PhpStorm 的 Terminal 視窗啟動即可。

為了能夠使用 Xdebug ，我們需要在容器啟動之前，在 .env 檔案中啟用這個功能，加入以下鍵值即可

SAIL_XDEBUG_MODE=develop,debug

加入後啟動容器

vendor/bin/sail up -d

由於透過 Laravel Sail 的開發環境，位於主機的 PhpStorm 並無法直接訪問到 PHP 直譯器，但是 PhpStorm 支援透過 Docker 配置它

使用 PhpStorm 來開發和 Debug Laravel Sail 專案

按如圖所示操作新增位於 Docker 內的 PHP 直譯器，注意 PHP language level 一項也需要手動選擇為與 Docker 內一致的版本。

使用 PhpStorm 來開發和 Debug Laravel Sail 專案

訪問瀏覽器的擴充套件商店搜尋 XDebug Helper 並安裝

如果使用 Edge 可以直接訪問 Xdebug helper - Microsoft Edge Addons

使用 PhpStorm 來開發和 Debug Laravel Sail 專案

在 File >> Setting >> PHP >> Servers 按如圖配置

使用 PhpStorm 來開發和 Debug Laravel Sail 專案

開啟 PhpStorm 的 XDebug 監聽

使用 PhpStorm 來開發和 Debug Laravel Sail 專案

隨機修改 routes/web.php 中的程式碼，這裡使用

Route::get('/', function () {
    $a = 1;
    return view('welcome');
});

在 return 語句打上斷點

image-20220117180126685

啟用 XDebug Helper 的 Debug 模式，並重新整理 localhost 頁面

image-20220117180156316

此時 PhpStorm 可能彈出 Debug 連線的視窗，連線即可，便可以看到斷點的 Debug 資訊：

image-20220117180305023

快取了路由又在 web.php 打斷點

使用了 sail php artisan route:cache 後，路由將直接由快取載入，將無法訪問到程式碼中的斷點。可使用以下命令清除路由快取：

sail php artisan route:clear

PhpStorm 路徑對映配置錯誤

在配置 PhpStorm 的 Server 時，遠端的絕對路徑應該是 /var/www/html，這是專案在容器中的路徑，而非專案在子系統中的路徑。

PhpStorm 官方文件

Laravel Sail 官方文件

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程 | myhui0926 | LearnKu

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章