larry 覺得這篇文章很好是在於，除了 API 串接的架構我們可以參考，另外關於 PHP 的寫法 (包含 PHP 8 的新語法)，還有一些軟體工程的概念，都很值得我們參考。

這篇教程是以範例的方式來進行。首先，新增一個 service
app/Services/MedicalTrust/MedicalTrustService.php

Laravel service container 的觀念，要做 service container binding

// app/Providers/AppServiceProvider.php

public function boot()
{
    $this->app->singleton(MedicalTrustService::class,
        fn () => new MedicalTrustService(
	    baseUrl: ‘......’,
            apiToken: ‘.....’,
	),
    );
}

注意教程範例中，MedicalTrustService 本身就是 concrete class，也沒有 implement 任何介面，其實不用特別寫 binding (系統會自動 resolve)。他這樣寫應該是為了餵參數進去，如果參數寫在 service 裡面，binding 這一段其實可以省掉。

新增一個 trait
app/Services/Concerns/BuildsBaseRequest.php

這邊用的是 Laravel HTTP Client 的用法
https://laravel.com/docs/9.x/http-client

trait BuildsBaseRequest
{
    public function buildRequestWithToken(): PendingRequest
    {
        //…
    }

    public function buildRequestWithDigestAuth(): PendingRequest
    {
        //…
    }
}

新增一個 trait
app/Services/Concerns/CanSendGetRequest.php

trait CanSendGetRequest
{
    public function get(PendingRequest $request, string $url): Response
    {
        return $request->get(
    	    url: $url,
    	);
    }
}

新增一個 trait
app/Services/Concerns/CanSendPostRequest.php

trait CanSendPostRequest
{
    public function post(PendingRequest $request, string $url, array $payload = []): Response
    {
        return $request->post(
    	    url: $url,
    	    data: $payload,
    	);
    }
}

注意這份教程所有輸入參數到 function，都使用 PHP 8 Named Arguments 的語法。

還記得本文最上方新增的
app/Services/MedicalTrust/MedicalTrustService.php
此時就可以把這些 trait 都用上

class MedicalTrustService
{
    use BuildBaseRequest;
    use CanSendGetRequests;
    use CanSendPostRequests;
 
    // PHP 8 的 Constructor property promotion
    public function __construct(
        private readonly string $baseUrl,
        private readonly string $apiToken,
    ) {}

    // ...
}

注意這份教程所有 class constructor，都使用 PHP 8 Constructor property promotion 的語法。

新增一個 service
app/Services/MedicalTrust/Resources/DentalResource.php

class DentalResource
{
    public function __construct(
        private readonly MedicalTrustService $service,
    ) {}
 
    public function list(string $identifier): Response
    {
        return $this->service->get(
    	    request: $this->service->buildRequestWithToken(),
    	    url: "/dental/{$identifier}/records",
    	);
    }
 
    public function addRecord(string $identifier, array $data = []): Response
    {
        return $this->service->post(
            request: $this->service->buildRequestWithToken(),
    	    url: "/dental/{$identifier}/records",
    	    payload: $data,
    	);
    }
}

MedicalTrustService 注入了 DentalResource，也可以說是 DentalResource 再包裝 MedicalTrustService。

注意這種寫法，MedicalTrustService 把牙醫的 API 實作完全分離出去了。也就是如果我們要新增，例如復健科，要另新增一個 RehabResource.php

教程的作者提到，這樣寫可以，但要輸入 payload 時，很有可能是長長一段 json 或是 array，所以教程的作者希望把 API 輸入做成 object。下面重寫了 function addRecord，把 payload 用 NewDentalTreatment object 去實作 (larry 本篇重點是了解 whole picture，資料結構做成物件的細節我們先不看)。

class DentalResource
{
    // 省略

    public function addRecord(string $identifier, NewDentalTreatment $request): Response
    {
        return $this->service->post(
      	    request: $this->service->buildRequestWithToken(),
      	    url: "/dental/{$identifier}/records",
      	    payload: $request->toArray(),
        );
    }
}

在調用端 (caller side)，我們新增一個 
app/Http/Controllers/Dental/Crowns/StoreController.php

class StoreController
{
    public function __construct(
        private readonly DentalResource $api,
	private readonly DentalTreatmentFactory $factory,
    ) {}
 
    public function __invoke(NewCrownRequest $request): RedirectResponse
    {
        // do some request validation here
	// if fails, throw Exception

    	$treatment = $this->api->addRecord(
    	    identifier: $request->get('patient'),
    	    request: $this->factory->make(
  	        attributes: $request->validated(),
  	    ),
  	);

  	// ...
    }
}

所以整個架構是 MedicalTrustService 注入 DentalResource，DentalResource 注入 controller。注意 controller function 的參數是 NewCrownRequest。

NewCrownRequest 是 custom form request，$request->validated() 將 post 資料餵給 factory，產生 NewDentalTreatment object，餵給 DentalResource。

Again，我們這篇主要是理解 whole picture，所以 factory method 如何產生 object 這一段我們暫時不看。

結論

基本上 get / post 等基礎工程寫在 MedicalTrustService，它是一個非常通用的 service。DentalResource 做的是針對這組 API，做 post 參數的格式，並將 payload 物件化，開有語意的 function 給 caller 端使用。將 DentalResource 注入 controller 就可以使用了。

本篇除了參考原教程作者串 API 的架構，另外就是參考他 PHP 的寫法。例如 trait 的使用，為什麼要用 MedicalTrustService 注入 DentalResource 這樣的分層。他也大量使用 PHP 8 的新寫法 Named Arguments 以及 Constructor property promotion。輸入的 array 資料物件化的部分也可以參考一下。

larry 最後想提的是，我們要參考的是原教程為什麼要這樣寫的精神，而不是拘泥於它的架構。實際上我們架構如何設計與撰寫，應該還是以實際的狀況和需求來判斷。

https://www.php.net/releases/8.0/en.php

Named Arguments 命名參數

舉例來講，function htmlspecialchars 的 prototype

function htmlspecialchars(
    string $string,
    int $flags = ENT_COMPAT,
    string $encoding = null,
    bool $double_encode = true
)

如果只是要指定其中一個參數 double_encode，其他用預設值，PHP 8 可以這樣寫

htmlspecialchars($string, double_encode: false);

注意 flags, encoding 都不用輸入。官方文件並提到，使用 Named Arguments 時參數不需要依照順序。

另外，如上方範例，Named Arguments 可以跟傳統輸入參數的方式混用。可以混用又沒有參數輸入的順序限制，會不會造成 ambiguous。如果用 coding convention 去限制，又會造成開發上的成本。larry 個人是對這個新功能持保留態度。

Constructor property promotion

在 PHP 8，constructor arguments 可以直接宣告成 class 的屬性。如下範例，注意 constructor arguments 前直接加了 public modifier。

class Point {
  public function __construct(
    public float $x = 0.0,
    public float $y = 0.0,
    public float $z = 0.0,
  ) {}
}

這樣 x, y, z 就直接宣告成 class 的屬性，不需要另外宣告

class Point {
  // 不需要
  public float $x;
  public float $y;
  public float $z;
  ...
}

這樣的確簡化了很多程式碼，但少了明文定義 class 的屬性。這樣真的不會造成混淆嗎？而且一樣，如果用 coding convention 去限制，又會造成開發上的成本。對這個新功能我還是持保留態度。

Match expression (match 表達式)

echo match (8.0) {
  '8.0' => "Oh no!",
  8.0 => "This is what I expected",
};
// print “This is what I expected”

match 表達式是 PHP 8 新出的。與 switch 判斷式比較，match 表達式會直接 return 數值，並用 strict comparison 做輸入/選項比較。相對的，switch 判斷式是 loose comparison。所以如果用 switch，輸入 8.0，會先找到字串的 ‘8.0’。

寫法跟應用上 larry 還是不太習慣。match 大括號裡的東西比較像 array 的寫法，卻用大括號包住。應用上也有點 array 的味道，那直接使用 array 相關 function 反而還清楚一點。

Nullsafe operator

$country = $session?->user?->getAddress()?->country;

如果 $session 有值，return $session->user。如果 $session->user 有值，return $session->user->getAddress()，依此類推。從左到右，每一個問號會評估一次是否為 null，如果不為 null，繼續往右走。如果為 null，中斷在為 null 的部分，並 return null。

讀者可以評估一下上面 sample code，如果以 if else 來寫，或以三元運算子來寫，會有多少程式碼。用 nullsafe operator 除了簡潔以外，語意上也清楚。這個新功能 larry 會考慮使用。

Saner string to number comparisons 較健康的字串 / 數字比較

0 == 'foobar';
// PHP 7 和 PHP 7 以前會 return true
// PHP 8 會 return false

在 PHP 7 和 PHP 7 以前，上面 sample code 比較的方式是字串 “foobar” 先嘗試 cast 成數字，發現沒辦法 cast，所以 cast 成 0，所以上面比較式 return true。

這部分是 PHP 語言長期的一個缺陷，尤其當使用 in_array, switch 等包含 implicit comparison 時，最好自己先判斷會不會有字串 / 數字比較的情況，不然 implicit comparison 判斷可能有誤。

PHP 8 修正了這個錯誤，除了將字串 cast 成數字外，也會將要比較的數字 cast 成字串，字串對字串比較。也就是比之前多了一個比較條件。

Just-In-Time (JIT) compilation

PHP 是直譯式語言 (interpreted language)，要先裝好 PHP 套件，執行時 PHP code 會在 PHP 套件的環境裡，也可以說是透過 PHP 套件，不用編譯，直接執行。

PHP 8 推出的 Just-In-Time (JIT) compilation，會在執行期間，自動將某些 code 編譯，主要是 JIT 引擎分析會頻繁執行的 code，進行編譯，以達成效能的最大化。

原本 PHP 要透過一個 Zend virtual machine 與 CPU 溝通。有了 JIT compiler，部分程式碼會被編譯，快取在記憶體裡。當第二次執行該段 code，又編譯碼的快取還在的話，就會繞過 Zend virtual machine，直接執行編譯碼與 CPU 溝通。

PHP 8 的 JIT compiler 有兩種：Tracing JIT 與 Function JIT。

Function JIT 會編譯整個 PHP functions，但不會去分析程式碼結構。Tracing JIT 則會去找到這些重複又頻繁執行的 code，進行編譯。Tracing JIT 因為編譯的總量少，能加快編譯的速度 (節省主機資源)，並在有限的記憶體 buffer，可以快取對整體效能最有幫助的編譯碼。

結論

PHP 8 大部份新寫法類型的功能，larry 是持保留態度，感覺對開發上沒有實質的幫助。PHP 8 修正了 PHP 語言長期的字串 / 數字比較問題，這件事需要知道一下。JIT 的部分也要知道，如果使用 PHP 8，JIT 的部分一定要正確 configure，開啟使用。