# Laravel Homestead
>[color=green] https://ithelp.ithome.com.tw/articles/10210529

[TOC]
## 前置動作
- 啟用 VT-x
:::danger
:bulb: 注意 windows 使用者名稱不要使用中文名，使用 vagrant 指令和產生 ssh key 很容易發生錯誤。
:::
- 下載/安裝 VirtualBox
- 下載/安裝 Vagrant

安裝完成後測試

$ vagrant --version

## 下載/安裝 Homestead Vagrant Box
透過 vagrant 指令，安裝 laravel/homestead 虛擬機

$ vagrant box add laravel/homestead

過程中會詢問 provider，輸入 3 (virtualbox) 後開始下載

### 安裝 Homestead

$ git clone https://github.com/laravel/homestead.git Homestead

可以在 GitHub 發布頁面上找到最新的穩定版本，透過 git 的 checkout 切到 7.20.0 版：

$ cd Homestead
$ git checkout v7.20.0

(以下指令皆在 Homestead 目錄下執行)

### 產生 Homstead 設定檔
輸入指令產生 Homestead.yaml

$ init.bat

### 設定 Homestead
初始值
- authorize、keys：設定登入虛擬機時使用的 SSH 金鑰，預設會使用自己家目錄底下的金鑰。若自己的家目錄底下沒有 key 的話，可以用 **`ssh-keygen -t rsa -C "[e-mail]"`** 指令產生，如果路徑錯誤或是沒有 SSH 金鑰，將無法啟動 Homestead。
- folder：設定掛載的虛擬目錄

folders:
    - map: D:/laravel
      to: /home/vagrant/laravel

- site：本地網域名稱

sites:
    - map: homestead.test
      to: /home/vagrant/laravel/public
      php: "^8.0" // 指定 php 版本
      type: apache // 指定 server

::: info
:bulb: map 對應的網址需設定 vhost
:bulb: 每次更改設定需重啟，運行 **`vagrant reload --provision`** 指令

:bulb:可設定多個多個站台

:::
### 啟動 Homestead Vagrant Box

$ vagrant up

### 登入 Homestead Vagrant Box

$ vagrant ssh

### 開啟時執行命令(執行指定 php 版本)
homestead 重啟時僅會執行 php 最高版本，可設定啟動時執行預設命令，加入「執行 php 指定版本」的命令

開啟`/Homestead/Vagrantfile`加入`config.vm.provision "shell", inline: "sudo service php{版本}-fpm start", run: "always"`

config.vm.provision "shell", inline: "sudo service php7.2-fpm start", run: "always"


## vagrant 指令
1. 啟動 Homestead：**`vagrant up`**
2. 登入 Homestead：**`vagrant ssh`**
3. 暫停 Homestead：**`vagrant suspend`**
4. 將 Homestead 關機：**`vagrant halt`**
5. 重啟 Homestead：**`vagrant reload --provision`**

## 錯誤處理
### 虛擬機安裝失敗
1. 找到 **`/Oracle/VirtualBox/drivers/network/netadp6`**
2. 右鍵點擊 **`VBoxNetAdp6.inf`** 選擇安裝
### 虛擬機重開後 http 502
>[color=green]https://learnku.com/laravel/t/24634

虛擬機啟動對應的 php 版本 fpm

$ sudo service php7.2-fpm start

### VERR_INTNET_FLT_IF_NOT_FOUND 錯誤
找不到系統對應的網路卡，需要去更改網路卡名稱 (發生在 windows 更新後)

1. 查看所有網路卡名稱

$ Get-NetAdapter

EX: 出來結果

Name                      InterfaceDescription
----                      --------------------
vboxnet0                  VirtualBox Host-Only Ethernet Adapter

2. 更名

$ Rename-NetAdapter -Name "VirtualBox Host-Only Ethernet Adapter" -NewName "vboxhost1"

## phpMyAdmin
>[color=green]https://medium.com/zrealm-ios-dev/%E9%87%8D%E7%81%8C%E7%AD%86%E8%A8%981-laravel-homestead-phpmyadmin-%E7%92%B0%E5%A2%83%E5%BB%BA%E7%BD%AE-87090f101b9a

:::danger
:bulb:phpMyAdmin - 錯誤
設定檔權限錯誤，檔案不應讓所有人可以寫入！

解決方式：編輯 `config.inc.php`
>[color=red]https://ubuntuqa.com/zh-tw/article/6895.html

$cfg['CheckConfigurationPermissions'] = false;

:::

## 外部連線進 MySQL (以 HeidiSQL 為例)
1. 找到 homestead MySQL 對應的 port

2. 輸入 homestead 帳號密碼 (預設 homestead/secret) 及對應 port (2200)

## 切換 php fpm 版本
列出目前有的版本，然後輸入要切換的版本的順序號即可

$ sudo update-alternatives --config php


## 信任憑證
1. ssh 後將對應網域的憑證複製到共用資料夾 `/vagrant/`

$ cp /etc/nginx/ssl/supplier.test.crt /vagrant/

2. 到 Homestead 目錄下安裝該憑證

:::warning
:bulb: 檢查憑證安裝
1. 按下 `win` + `R` 並輸入 `certmgr.msc`
2. 點選 受信任的根憑證授權單位 > 憑證 檢查是否在裡面

:bulb: chrome 有可能會快取住憑證，若還是顯示不安全可以切換瀏覽器看看
:::

## Xdebug
:::danger
Xdebug 3.x 僅支援 php 8.1 以上版本 (2025.03.26)
請參閱: https://www.php.net/supported-versions.php
:::
1. 至對應的 php 版本 fpm 並編輯

$ sudo vim /etc/php/{php-version}/conf.d/20-xdebug.ini

:::warning
:bulb: 沒有 `20-xdebug.ini` 怎麼辦?

$ sudo apt update
$ sudo apt install php{php-version}-xdebug -y

:::
2. 添加相關資訊

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host={windows ip}
xdebug.client_port=9003

:::info
:bulb: windows ip 如何查看?
cmd 輸入 `ipconfig` 找到正在使用的網路卡的 IPv4 位址
:::

3. 安裝插件 PHP Debug

4. 設定 launch.json

{
    // 使用 IntelliSense 以得知可用的屬性。
    // 暫留以檢視現有屬性的描述。
    // 如需詳細資訊，請瀏覽: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "{virtualbox_project_path}": "{local_project_path}"
            }
        },
    ]
}

:::info
:bulb: `pathMappings` 可以看 `Homestead.yaml` 的設置
:::

## 遷移 VM VirtualBox (待確認)
1. 將 `/.vagrant.d`、`/.VirtualBox`、`/VirtualBox VMs`、`/Homestead` 移至目的位置
2. 修改 `/.VirtualBox/VirtualBox.xml` 的路徑至目標位置

...
    <MachineRegistry>
      <MachineEntry uuid="{uuid}" src="D:\VirtualBox VMs\homestead-7\homestead-7.vbox"/>
    </MachineRegistry>
...
    <SystemProperties defaultMachineFolder="D:\VirtualBox VMs" defaultHardDiskFormat="VDI" VRDEAuthLibrary="VBoxAuth" webServiceAuthLibrary="VBoxAuth" LogHistoryCount="3" proxyMode="0" exclusiveHwVirt="false"/>
...

3. 修改 VM VirtualBox
- 檔案 > 喜好設定 > 預設機器資料夾改為新位置
- 加入新位置的機器