Laravel – Larry的午茶時光

Laravel 11 發布與新功能！最低要求 PHP 8.2，檔案結構已大改，Laravel Reverb 套件支援 WebSocket

Larry — Sun, 24 Mar 2024 09:00:46 +0000

https://laravel-news.com/laravel-11
前幾天 (2024年3月中) Laravel 11 發布了。要先提醒讀者的是，Laravel 11 是一個超大的改版，要不要使用 Laravel 11 要再三思。

以下是 Laravel 11 的一些主要更新和新功能：

PHP 8.2 是 Laravel 11 最低的 PHP 版本要求

Laravel 目前的策略看起來是跟著 PHP 的最新版本。Laravel 9 要求 PHP 8.0，Laravel 10 要求 PHP 8.1，Laravel 11 要求 PHP 8.2。

但這個策略會有一個副作用：系統廠商跟開發者不可能隨時都去更新 PHP 版本，設限一個這麼高的 PHP 版本，反而會限制新版 Laravel 的普及。

Streamlined Directory Structure (簡化以及提高效率)

bootstrap/app.php 檔案重寫，而且專案層級的設定會寫在這裡 (Laravel 10 以前這個檔案根本不會打開)。

一些專案層級的 routing, middleware, service providers, exception handling 等，都在這個檔案設定，而不是散落在專案四處。

Laravel 10 app/Providers 底下有 5 個 providers，Laravel 11 app/Providers 底下只有 AppServiceProvider。之前其他 service provider 的功能整合到 bootstrap/app.php，或是直接在 AppServiceProvider 中設定。

舉例來說，auth policy 之前是註冊在 AuthServiceProvider，Laravel 11 是註冊在 AppServiceProvider。

routes/api.php，routes/channels.php 已被移除，因為很多應用並沒有用到這些檔案。當然，可以用 artisan 指令新增回來。

app/Http/Middleware 整個資料夾不見了！現在都在 bootstrap/app.php 中設定 (withMiddleware closure)。

app/Http/Kernel.php 也移除了！因為它的功能本來就是管理 middleware，現在 Middleware 整個資料夾都不見了，當然也不需要 Kernel.php 了。

app/Console 整個資料夾也不見了！scheduled tasks 直接寫在 routes/console.php (它預設還在)。如果是用 artisan 指令新增 command，仍然會在 app/Console/Commands 底下。

app/Exceptions 整個資料夾也不見了！exception handling 的設定就直接寫在 bootstrap/app.php。

app/Http/Controllers/Controller.php 變成一個空的 abstract class，不再 extends 任何東西。

預設的 database 變成 SQLite (而不是 MySQL)

SQLite database 其實就是一個檔案，當然比 MySQL 輕量、跨平台，以及更低的軟體相依性。但目前 MySQL 還是最多人使用的 database，使用 MySQL 的開發者要記得 DB 設定要切到 MySQL。

新增 Laravel Reverb 套件支援 WebSocket

Laravel Reverb 是一個支援 WebSocket 的套件。傳統 HTTP 是一問一答，但如果 client 不問，並不會知道主機資料已經變化。所以傳統是用「輪詢」(Polling) 的方式，例如每幾秒、每幾分鐘問一次主機。

經由 WebSocket 後主機可以主動通知 client：主機資料已經改變了。實際應用場景包含訊息推播、即時訊息更新，等等。client 端不需詢問主機或重整網頁。

Per-second rate limiting

之前 rate limiting 是寫在 App\Providers\RouteServiceProvider，而且只能以「每分鐘」為單位來限制。

Laravel 11 沒有 RouteServiceProvider，所以是寫在 AppServiceProvider，而且可以「每秒鐘」為單位來限制。
https://laravel.com/docs/11.x/routing#rate-limiting

Health routing

定義在 bootstrap/app.php，有一個 /up，方便第三方 health check 軟體，例如 Kubernetes 來使用。當 request /up 時，Laravel 會發一個 DiagnosingHealth event，開發者可以接這個 event，再做一些確認健康動作。

Encryption Key Rotation

Laravel 會加密所有 cookie，包含 session cookie。Laravel 11 新增一個環境變數 APP_PREVIOUS_KEYS。開發者可以將之前用來加密的 key (多筆)，以逗號分隔的方式，存在 APP_PREVIOUS_KEYS。

Laravel 仍會用 APP_KEY 加密，解密時仍會先用 APP_KEY，不行時再從 APP_PREVIOUS_KEYS 中一一嘗試。

這樣開發者就可以更改 APP_KEY，並將舊的 key 放在 APP_PREVIOUS_KEYS，而不影響所有使用者操作。

Automatic Password Rehashing

Laravel 是以 bcrypt 加密密碼，其中有一個參數 BCRYPT_ROUNDS，在 config/hashing.php 中使用。當開發者重新設定環境變數 BCRYPT_ROUNDS 後，當使用者登入或 auth，Laravel 11 會 re-hash 使用者密碼。

Prompt validator

Laravel Prompts 套件在 Laravel 10.17 加入。用 artisan commands 的方式可以撰寫一些客製的指令以及回覆。

其中可以檢查 console 的輸入值是否 valid。Laravel 11 開始可以使用 validator (request validate 的那種寫法)，來檢查 console 的輸入值。

Queue interaction testing

之前如果要對 queued jobs 做單元測試，是非常麻煩的。Laravel 11 開始 queued job 可以生成一個 fake instance，直接在主執行緒上做測試以及 assert。

New artisan commands

這幾個指令終於加到了 artisan command

php artisan make:class
php artisan make:enum
php artisan make:interface
php artisan make:trait

Attribute Casting 的更改

之前是用 property 來設定 casts，Laravel 11 開始請用 method 來設定 casts，這樣在 casts function 裡還可以做複雜的變化 (call 其他 methods)。

https://laravel-news.com/laravel-11 的範例

protected function casts(): array
{
    return [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
        'options'=› AsEnumCollection::of(UserOption::class),
    ];
}

總結

以上是 Laravel 11 幾個重要的更新。當然在本文上述之外，還有其他的更新。

Laravel 10 之前的更新基本上都是新增功能，或是某個模組的翻新。Laravel 11 則是超大幅度的程式重構，當然寫法也都完全不同。

https://laravel.com/docs/10.x/reverb
另外，新的 Laravel Reverb 套件(支援 WebSocket)，需要 Laravel 10.47 以上，以及 PHP 8.2 以上。

Laravel 11 本身有超大幅度的程式重構，主機環境也需要 PHP 8.2 以上。開發者如果要使用 Laravel 11，要想清楚喔。

Laravel Passwordless Authentication 無密碼驗證登入，使用 Signed URL (簽署過的網址)

Larry — Sun, 23 Jul 2023 05:00:59 +0000

Passwordless Authentication 無密碼驗證登入是這幾年有在討論的技術議題，包含微軟、Google、Apple 態度上應該都是往這方向走。

無密碼登入的實現方式包含：登入時在預先綁定的 mobile device 壓指紋驗證。或是傳簡訊或 Email 到之前註冊的手機或信箱，使用者依照簡訊或 Email 的內容 (通常是一串碼)，輸入網站做登入，等等。

實踐的方式各有變化，撰文的現在 (2023年7月) 還沒有一個通用的規範。

larry 之前關於中華電信 Hami Video 的文章，Hami Video 就是用手機簡訊方式做無密碼登入。當然，那篇文章也提到：Hami Video 的背後是中華電信，只有電信商才能負擔這麼大量的手機簡訊費用。

無密碼登入適合哪種用戶使用？

無密碼登入適合哪種用戶使用？特別適合網站的低頻使用用戶，甚至一次性、或是幾個月、一兩年才使用一次的用戶。對於這些用戶，他們不用去管理密碼，並保密自己的密碼，自己設定的密碼強度也有可能不夠。

「保密自己的密碼」這句話邏輯上似乎有點好笑。但根據 larry 這麼多年服務客戶的經驗，還是有人直接密碼明碼給別人，請別人幫忙去處理事情。不是說不相信別人，而是我們就事論事，這樣密碼就有可能外洩。

有時候教育的成本很高，還不如設計無密碼登入。

Laravel 官網的文章與範例

今年 (2023) 三月份，larry 看到 Laravel 官網有一篇關於無密碼登入的文章。它是用寄 Email 給用戶的方式，Email 中包含一個簽署過的網址 (Signed URL)，用戶點該連結後直接登入。
https://laravel-news.com/passwordless-authentication-in-laravel

這篇 Laravel 官網文章有附作者的 GitHub Repo，程式架構的東西看文字不一定好懂，直接從作者的 sample project 來看可能會更為理解。

首先 resources/views/app/auth/login.blade.php 中包含了

resources/views/app/auth/register.blade.php 中包含了

它是用 Laravel Livewire 開發的，讀者不一定要使用 Livewire，本篇重點在理解 Laravel 官網文章的概念。

Livewire 的 component 概念可以參考我之前的文章 Laravel Blade Templates：Components, Slots, and Building Layouts

其中 class based component 的概念，Livewire 應該是基於此開發的。

上方提到的對應到 app/Http/Livewire/Auth/LoginForm.php

對應到 app/Http/Livewire/Auth/RegisterForm.php

使用者送出 Email 時會觸發 LoginForm::submit 這個 function，裡面會觸發 app/Actions/Auth/SendLoginLink.php

SendLoginLink::handle 裡面會使用 Laravel 內建的 URL::temporarySignedRoute 將你指定的網址簽章編碼，並設定該連結的有效期限。Signed Route 是 Laravel 5.6 開始支援，時間過的真的好快啊。

SendLoginLink::handle 將簽章編碼好的連結傳給 Mailable，並寄給用戶。Mailable 是 app/Mail/Auth/LoginLink.php

使用者收信點連結後導回網站，由 controller LoginController::__invoke 檢查簽章、登入、以及轉向指定網頁。

以上就是整個 Email 用戶 Signed URL，使用者無密碼登入的流程。Laravel 官網文章也有附使用者無密碼「註冊」的 sample code，但只是無密碼登入的變化，這裡就不再重複。

結語

Passwordless Authentication 無密碼驗證登入不只是一個登入方式的變化，而是很值得參考的網路科技的趨勢，至少包含微軟、Google、Apple 態度上應該都是往這個方向走。

本篇討論的 Laravel 官網文章是用 Email 用戶 Signed URL 的方式，Laravel 早已有簽章網址的模組，可以很輕易且漂亮的實作，並且可以指定簽章網址的有效期限。

除了無密碼登入，很多商業應用都可以使用 Signed URL 的方式。Signed URL 概念上、實作上，應該是一個滿值得大家了解的功能。

Laravel Eloquent Accessor、Mutator & Attribute Casting，Laravel 9 開始已大改

Larry — Sun, 23 Apr 2023 13:51:54 +0000

去年 (2022) 發布的 Laravel 9 中，Eloquent Accessor & Mutator 迎來了一次大改，Attribute Casting 的部分則是調整不大。

伴隨著 PHP 8.1 的釋出，Laravel 8 的後繼版本已經支援 Enum Casting (當然 Laravel 9 之後的版本也會支援)。

延伸閱讀：Laravel 9 的新功能：最低要求 PHP 8.0，底層更新為 Symfony 6.0，開始使用 PHP 8.1 的 Enum

larry 想藉 Laravel 9 大幅更新 Accessor & Mutator 的這個機會，走一遍 Mutator & Casting 的官方文件。本篇文章會以 Laravel 9 Mutator & Casting 官方文件為主。
https://laravel.com/docs/9.x/eloquent-mutators

首先，依照官方文件的語意，Accessor 指的是 get 這個動作，Mutator 指的是 set。

什麼時機會使用到 Accessor / Mutator 呢？例如，每次存一個值都要 encrypt，或是取出來用時都要 decrypt。或是，你要每次都要把 array 轉成 json 存到資料庫，使用時取出 json 要再轉回 array。

也就是，如果你每次「存」或「取」都要做一定動作，可以考慮使用 Accessor / Mutator。Laravel 9 開始，假如你要存取一個 model 裡的 first_name attribute，要這樣寫

use Illuminate\Database\Eloquent\Casts\Attribute;

// 注意有 return type
// 注意是 protected method, 不允許調用端直接調用
protected function firstName(): Attribute
{
    // 可以只寫 get 或 set 其一
    return Attribute::make(
        get: fn ($value) => ucfirst($value),
        set: fn ($value) => strtolower($value),
    );
}

有時後程式邏輯需要把資料庫中的幾個欄位，重組成一個新的 object，Laravel 稱之為 value object。

use Illuminate\Database\Eloquent\Casts\Attribute;

// 注意是 protected method
// 當調用端存取 address 時會觸發這個 function 
// 也就是自動新增了一個 address attribute
protected function address(): Attribute
{
    // class Address 就是所謂的 value object
    return Attribute::make(
        get: fn ($value, $attributes) => new Address(
            $attributes['address_line_one'],
            $attributes['address_line_two'],
        ),
        set: fn (Address $value) => [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ],
    );
}

讀者可以觀察一下，get / set 使用的都是 PHP 7.4 的 arrow function。get return 的是一個新生成的 object，set 中設定的是一個 array。

class Address 就是所謂的 value object。調用端要使用，會像是 $user->address->lineOne。

定義 value object 時，lineOne、lineTwo 都要是 public。

class Address
{
    public $lineOne;
    public $lineTwo;

    public function __construct(...)
    {
        //…
    }
}

其實把 DB 中的欄位重新包裝成 value object (如上方的 class Address)，在程式邏輯中使用，已經算是 Attribute Casting。Laravel 提供了一個不用寫 Accessor / Mutator 的方式，將 DB 欄位轉成常用的資料格式。

Attribute Casting

例如 Laravel 的 DB migration boolean，實際在 MySql 裡是 tinyint(1)，存的值是 1 或 0。這時你可以 cast 成 boolean。

use Illuminate\Database\Eloquent\Casts\AsStringable;
use Illuminate\Database\Eloquent\Casts\AsArrayObject;
use Illuminate\Database\Eloquent\Casts\AsCollection;

class User extends Model
{
    protected $casts = [
        'is_admin' => 'boolean',
        'directory' => AsStringable::class,
        'options' => 'array',
        // 也可以 cast 成 PHP ArrayObject 或 Laravel Collection
        //'options' => AsArrayObject::class,
        //'options' => AsCollection::class,
    ];
}

也就是如果 DB migration 是 boolean，這樣可以使用沒錯。但如果要寫漂亮一點，model attribute 可以 cast 成 boolean。字串的部分，你也可以 cast 成 Laravel fluent string，方便後續操作。

另外，如果你的 DB migration 有 json 或 text，model attribute 可以 cast 成 array，存取時自動會在 array 和 json 格式轉換。等同於資料庫欄位可以直接存 array，這是很有趣的。

接下來是一個重要功能 Enum Casting (僅支援 PHP 8.1 以上的環境)

use App\Enums\ServerStatus;
 
protected $casts = [
    'status' => ServerStatus::class,
];

這樣要存或取 $model->status 都會直接轉換成 enum。

if ($server->status == ServerStatus::Provisioned) 
{
    $server->status = ServerStatus::Ready;
    $server->save();
}

Custom Casts

如果你執行 Artisan command

php artisan make:cast YourClass

就會新增一個 YourClass 在 app/Casts 目錄下。例如 class Address

use App\ValueObjects\Address as AddressValueObject;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class Address implements CastsAttributes
{
    public function get($model, $key, $value, $attributes)
    {
        // 將 DB 欄位轉成 value object return
        return new AddressValueObject(
            $attributes['address_line_one'],
            $attributes['address_line_two']
        );
    }

    public function set($model, $key, $value, $attributes)
    {
        if (! $value instanceof AddressValueObject) 
        {
            //throw exception
        }
 
        // return array 去設定 DB 欄位
        return [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ];
    }
}

記得文章上方的 Accessor / Mutator，使用的是 PHP 7.4 的 arrow function。function expression 內容就如同上方範例，只是 Custom Casts 把程式獨立到一個 class。

記得要設定 model，這樣等於新增了一個 address attribute (DB 存的是 address_line_one, address_line_two)

use App\Casts\Address;
 
protected $casts = [
    ‘address’ => Address::class,
];

結語

Accessor / Mutator 與 Casting 是一體的兩面。你可以寫 Accessor / Mutator，但如果正好有 Laravel 預先定義的 cast 資料類型，就直接用 casting 比較方便，包含 PHP 8.1 的 enum。

使用情境上，如果每次存取資料都有一個固定動作，可以考慮使用 Accessor / Mutator 或 Casting。例如每次存一個值都要 encrypt，或是每次都要把 array 轉成 json 存到資料庫，使用時取出 json 要再轉回 array。

或是轉成 Laravel Stringable 或 Collection 等資料格式，方便後續處理。將幾個 DB 欄位重新包裝成 value object 也是一個使用情境。

Accessor / Mutator 與 Casting 不是 Laravel 的大主題，但實際走過文件，還是有很多細節要注意。希望大家在資料庫欄位 / 程式邏輯之間的轉換 (ORM，Object Relational Mapping)，也有更深一層的理解囉。

Laravel 10 的新功能：最低要求 PHP 8.1，Laravel Pennant 實現 feature flag，Process facade 執行外部程式

Larry — Sun, 26 Feb 2023 09:29:55 +0000

https://laravel-news.com/laravel-10
前幾天 (2023年2月中) Laravel 10 發佈了。

我之前的文章 Laravel 9 的新功能有提到，從 Laravel 9 開始，major version 每一年更新一次，目前是訂在每年的二月更新 major version。

以下是 Laravel 10 的一些主要更新和新功能：

PHP 8.1 是 Laravel 10 最低的 PHP 版本要求

PHP 8.0 不行喔，檢查你的主機環境是不是 PHP 8.1 以上，才有辦法跑 Laravel 10。

新的 Laravel Pennant 套件

Laravel 10 發佈了新的 Laravel Pennant 套件。Laravel Pennant 的邏輯是，先定義一個使用者的條件，也許他是 beta tester，也許他是公司中某些指定的用戶。

這就是軟體工程的 Feature Flag。在「正式站」中上線多個程式碼分支，只有預先定義的部分用戶，可以使用新功能以及做最終測試。

參考官方文件 https://laravel.com/docs/10.x/pennant

來自上方文件的 sample code，你可以在 AppServiceProvider 定義使用者的資格

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Feature::define('new-api', fn(User $user) => match (true) {
            $user->isInternalTeamMember() => true,
            $user->isHighTrafficCustomer() => false,
            default => Lottery::odds(1 / 100),
        });
    }
}

‘new-api’ 字串是你定義的 feature name。larry 很喜歡這一段 sample code，是因為它同時用了 PHP 7.4 的 arrow function，和 PHP 8 的 match expression。

字面上看，如果用戶是內部 team member，或「不是」高流量的客戶，都給這個用戶使用 ‘new-api’。如果用戶「不是」內部 team member，又使用了高流量，就會 return default: 抽籤決定這個用戶可不可以使用 ‘new-api’。

這段 sample code 寫得很漂亮，很有意思。

上面 ‘new-api’ 是字串，也可以改為使用 class based 寫法

namespace App\Features;
  
class NewApi
{
    /**
     * Resolve the feature's initial value.
     */
    public function resolve(User $user): mixed
    {
        return match (true) {
            $user->isInternalTeamMember() => true,
            $user->isHighTrafficCustomer() => false,
            default => Lottery::odds(1 / 100),
        };
    }
}

你在 controller 裡就可以用 Feature::active 或 Feature::when 去確認使用者資格，並做相對應的動作

public function index(Request $request): Response
{
        return Feature::active(NewApi::class)
                ? $this->resolveNewApiResponse($request)
                : $this->resolveLegacyApiResponse($request);
}

public function index(Request $request): Response
{
        return Feature::when(NewApi::class,
            fn() => $this->resolveNewApiResponse($request),
            fn() => $this->resolveLegacyApiResponse($request),
        );
}

以上大概就是 Laravel Pennant 的邏輯。不用這個套件其實本來就可以寫這樣的效果，只是 Laravel Pennant 把這個需求的寫法架構化了。

新的 Process facade

https://laravel.com/docs/10.x/processes
新的 Process facade 讓開發者可以輕易的執行 Laravel 專案外，也就是作業系統層級的指令。例如官方文件的 sample code

use Illuminate\Support\Facades\Process;
 
$result = Process::run('ls -la');
// run function 是同步執行，也就是有可能會 hang 住 
return $result->output();

也可以指定要下命令的資料夾路徑

$result = Process::path(__DIR__)->run('ls -la');

上面 run function 是同步執行 (sync) 外部指令，也就是執行的當下有可能會 hang 住。而 start function 是非同步執行 (async)

$process = Process::timeout(120)->start('bash import.sh');
// 執行 120 秒沒完成的話，throw timeout exception 

while ($process->running()) {
    // ...
}
 
$result = $process->wait();
// 這一行會等 process 執行完 (有可能會 hang 住)
// 拿到 result

如果讀者是資深的軟體開發者，尤其是當年是 C++ 出身的，應該有感，這就是 multi-thread (多執行緒) 的概念啊。

Process facade 也包含了類似 thread pool 的功能。

use Illuminate\Process\Pool;
use Illuminate\Support\Facades\Process;
 
$pool = Process::pool(function (Pool $pool) {
    $pool->path(__DIR__)->command('bash import-1.sh');
    $pool->path(__DIR__)->command('bash import-2.sh');
    $pool->path(__DIR__)->command('bash import-3.sh');
})->start(function (string $type, string $output, int $key) {
    // ...
});

// 執行 import-1.sh, import-2.sh, import-3.sh
 
while ($pool->running()->isNotEmpty()) {
    // ...
}
 
$results = $pool->wait();

講到 multi-thread、thread pool，或是 process pool，真是讓我想起一些回憶，也許這就是寫部落格的好處之一吧，哈哈。

延伸閱讀，我2013年1月的文章：Multi-thread 多執行緒程式設計

Laravel framework 整個更新標示 function parameter type & return type

將現代 PHP feature 帶入 Laravel framework 中，明確的標示 function parameter type & return type。

Invokable validation rule 指令調整

// Laravel 9 產生 Rule Object with __invoke function
artisan make:rule Uppercase --invokable

// Laravel 10 做一樣的事，不用 --invokable flag
artisan make:rule Uppercase

新的 test 指令選項，顯示測試執行秒數

php artisan test --profile

上面指令會執行測試，並將每個測試的執行時間，由慢到快排序出來。開發者可以輕易找到，跑得過慢的測試。

新的 Str::password helper function

Str::password() 預設會產生 32 位長度的英文、數字、符號、空白，混合字串。輸入參數也可以指定字串長度。

結語

這次 Laravel 10 主要是 Laravel Pennant 和 Process facade 的導入。Laravel Pennant 功能上 larry 覺得還好，相同功能本來就可以用其他方式寫。倒是官方文件 sample code 同時用了 PHP 7.4 的 arrow function，和 PHP 8 的 match expression，這個寫法是很漂亮的。

Process facade 其實就是 multi-thread 程式設計。sync、async，甚至 thread pool 都實作出來了。如果開發者需要執行 Laravel 專案外，也就是作業系統層級的指令，應該是更方便了。

延伸閱讀：Multi-thread 多執行緒程式設計

Laravel Vite：繼 Laravel Mix 之後新的前端檔案管理工具

Larry — Sat, 10 Dec 2022 11:53:49 +0000

從 Laravel 5.4 開始 (2017/1/24)，前端檔案管理工具就是 Laravel Mix，我當年還有一篇關於 Laravel Mix 的文章

Laravel 9.19 開始 (2022/6/30)，Laravel 前端檔案管理工具從 Laravel Mix 改為 Vite。

每次寫關於軟體工程演進類的文章，都會有感於時間過得真的太快。2017~2022，五年多就這樣過去了。五年的時間，希望大家在人生中都有累積些什麼。

Laravel Mix 的底層是 Webpack，在 Laravel 根目錄會有 package.json, webpack.mix.js 兩支檔案。執行

npm install

會依照 package.json 去安裝套件到你的開發環境。

package.json 中有一個 “scripts” 欄位，定義了很多 npm 指令，並將 npm 指令轉成 mix 指令。mix 指令就會去跑 webpack.mix.js 這支檔案裡的 script，包含 compile css / js。

Laravel Vite 是基於 Vite，是一個基於原生 JavaScript ESM 的前端開發工具。與 Webpack 機制上不同的是，Webpack 一律依照 script 打包全部檔案素材 (dev mode 也是打包全部)。

而 Vite 在熱更新時 (hot module replacement，HMR)，是先 refresh 瀏覽器，檢查現在前端頁面有關的檔案是否有更新，如果有，才編譯與該頁面有關的檔案 (而不是每次都全部打包)。因此在開發階段，尤其是大型專案，會大幅加速開發時間。

Laravel Vite 一樣有 package.json，一樣要跑 npm install。只是根目錄 script 檔案不是 webpack.mix.js，改為用 vite.config.js。

Laravel Vite 的 package.json 中一樣有 “scripts” 欄位：

npm run dev  // 轉成 “vite”
npm run build  // 轉成 "vite build"

vite 指令就會去跑 vite.config.js 這支檔案裡的 script，預設是

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/sass/app.scss',
                'resources/js/app.js',
            ],
            refresh: true,
        }),
    ],
});

入口的 css / js 一樣是 resources/sass/app.scss, resources/js/app.js。注意有一個設定 refresh: true，這代表在執行 npm run dev 時，如果底下這幾個路徑檔案有更新

app/View/Components/**
lang/**
resources/lang/**
resources/views/**
routes/**

瀏覽器已 load 的頁面會整頁 refresh。以上是預設的監聽路徑，你也可以將自己想監聽的檔案路徑設定給 refresh 參數 (以設定 array 代替 true)，這樣 Vite 就會監聽你定義的路徑。

跟之前一樣 app.scss 中預設 import 隔壁的 _variables.scss。

app.js 中預設 import 隔壁的 bootstrap.js，在其中 load 你需要的套件，例如：jQuery，Bootstrap，Vue，等。

在前端檔案加一行 (與 Mix 不同，Vite 引用 css / js 在同一行)

@vite(['resources/sass/app.scss', 'resources/js/app.js'])

就可以將 compile 好的 css / js 引入 (並加 preload 屬性)。如果是 Build Mode (npm run build)，css / js 檔名會加上版本號 (auto-versioning)。

目前如果先安裝 laravel/ui，build 出來的 css / js 會包含 Bootstrap 5.2.3，是目前 (2022年12月) Bootstrap 的最新版。

Vite 也可以處理前端素材檔案，例如圖檔跟字型檔。在 JS 的入口處 (app.js) 寫入

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

執行 npm run build，這樣 Vite 就會將素材檔名編碼過，並移到 public folder 底下。前端要用素材檔可以這樣寫


{{--  --}}

結論

從 Webpack 到 Vite，底層是完全不同了。但可以看出來 Laravel Vite 創作時，作者盡量不動 Laravel 的架構，與之前一樣的 css / js 入口檔案。

Vite config 當然有一些獨立的功能和寫法。既然 Laravel 決定改用 Vite 了，我們應該也要隨之學習和習慣 Vite 的使用。

Laravel 官方網站關於第三方 API 串接的教程

Larry — Sun, 21 Aug 2022 10:49:06 +0000

前陣子看到 Laravel 官方部落格有一篇關於 API 串接，很好的文章
https://laravel-news.com/working-with-data-in-api-integrations

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

Laravel 9 的新功能：最低要求 PHP 8.0，底層更新為 Symfony 6.0，開始使用 PHP 8.1 的 Enum

Larry — Fri, 06 May 2022 08:48:56 +0000

https://laravel-news.com/laravel-9
今年 (2022) 二月 Laravel 9 發佈了。

從 Laravel 9 開始，major version 每一年更新一次。因為 Laravel 底層有使用 Symfony Framework 的元件，而且 Symfony 每年的 11 月會更新一次，所以 Laravel 目前是訂在隔年的二月更新 major version (這樣可以使用最新的 Symfony 版本)。像這次發布的 Laravel 9 底層是使用 Symfony 6.0。

以下列出 Laravel 9 的一些主要更新和新功能：

PHP 8.0 是 Laravel 9 最低的 PHP 版本要求

這是最根本的前提條件，檢查你的環境是不是 PHP 8.0 以上，才有辦法跑 Laravel 9。

route:list 指令顯示結果的重新設計

php artisan route:list

route:list 指令存在已久，如果 route 數量多而複雜，以前的顯示介面會有點混亂。Laravel 9 重新設計了 route:list 指令的顯示結果。

新的 test 指令選項，顯示測試覆蓋率

php artisan test --coverage

Laravel 的測試是基於 PHPUnit，Laravel 的測試功能存在已經非常久。上面指令會執行測試，並顯示每支程式的測試覆蓋率。

DB 預設使用 Anonymous Migration

Laravel 的 database migration，以前是要自己取 migration class name。但如果因需求變更，刪除再新增同一 DB table，或是多次修改同一 DB table，取 migration class name 就會變成一件麻煩事，migrate 起來的行為也不見得會跟你的邏輯順序相同。

Anonymous Migration 是 Laravel 8 後期推出的功能，Laravel 9 變成專案預設，以後再也不用取 migration class name 了。

新的 string functions

因為 Laravel 9 最低要求 PHP 8.0。PHP 8 新的 string functions: str_contains, str_starts_with, str_ends_with 也被引入，包裝成 Laravel 9 string functions: Str::contains, Str::startsWith, Str::endsWith

寄信件模組從 Swift Mailer 更新為 Symfony Mailer

Swift Mailer 為 Symfony Framework 的寄件元件，隨著 2021 年 11 月 Symfony 6.0 的推出，改為使用 Symfony Mailer，並停止維護 Swift Mailer。Laravel 9 也隨之改為使用 Symfony Mailer。

Eloquent Accessor / Mutator 有新的寫法

Laravel 8 以前的 Accessor / Mutator，例如你要存取一個 model 裡的 first_name attribute，要這樣寫

public function getFirstNameAttribute($value)
{
    return strtoupper($value);
}
 
public function setFirstNameAttribute($value)
{
    $this->attributes['name'] = $value;
}

Laravel 9 改成

use Illuminate\Database\Eloquent\Casts\Attribute;

// 注意有 return type
public function firstName(): Attribute
{
    // 官方文件是寫 Attribute::make(...
    // in this case, new 或 make 都可以
    return new Attribute(
        get: fn ($value) => strtoupper($value),
        set: fn ($value) => $value,
    );

    // 如果你是要 chain methods, 則是要用 Attribute::make(...
    // 例如
    /*
    return Attribute::make(
       ...
    )->shouldCache();
    */
}

用 PHP 8.1 的 enum 做 implicit route binding

https://laravel.com/docs/9.x/routing#implicit-enum-binding
官方文件的 sample code

// Category 為 enum
Route::get('/categories/{category}', function (Category $category) {
    return $category->value;
});

可以更漂亮的限制哪些參數是 route 可以允許的, 如果是不允許的參數, 直接 return 404.

用 Route::controller 將同一 controller 不同 route 更好的組織起來

Route::controller(YourController::class)->group(function () {
    …. // route 1
    …. // route 2
});

不用再重複寫 ControllerName，組織上，程式的簡潔度上都比較好。

用 PHP 8.1 的 enum 做 Eloquent Attribute Casting

官方文件的 sample code

use App\Enums\ServerStatus;

protected $casts = [
    'status' => ServerStatus::class,
];

你的 $model->status 不管是存，還是取，都會直接 cast 成一個 enum object.

if ($server->status == ServerStatus::Provisioned) 
{
    $server->status = ServerStatus::Ready; 
    $server->save();
}

https://laravel.com/docs/9.x/eloquent-mutators
包含上方的 Accessor / Mutator，以及這邊的 Casting，他們都屬於同一份文件，Laravel 9 在這份文件做了不少更新。

Route parameter scoping

https://laravel.com/docs/9.x/routing#implicit-model-binding-scoping
官方文件的 sample code

Route::get('/users/{user}/posts/{post:slug}', function (User $user, Post $post) {
    return $post;
});

如果是這種格式的 route，而且使用 custom key (:slug的部分)。Laravel 會自動 scope 該 user 底下的 posts.

Laravel 9 開始，如果沒使用 custom key，同樣也可以 scope child binding

Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
    return $post;
})->scopeBindings();

這樣寫法好處是更漂亮、更簡潔的檢查第一、二個參數的 relation.

Full Text Index & query by whereFullText

Laravel 9 開始, 如果使用 MySQL 或 PostgreSQL，可以使用 fullText method 做整段的 index。官方文件的 sample code

$table->text('bio')->fullText();

當 query 時，如果有 full text index 的欄位，可以使用兩個 method：whereFullText、orWhereFullText。官方文件的 sample code

$users = DB::table('users')
           ->whereFullText('bio', 'web developer')
           ->get();

Bootstrap 5 Pagination Views

Laravel 9 原生支援 Bootstrap 5 Pagination。在 AppServiceProvider, boot method, call

Paginator::useBootstrapFive();

即可使用 Bootstrap 5 Pagination View。

重新設計的 debug page

Laravel debug page 使用的是 Spatie Ignition，也重新設計了。

2 個新的 helper functions: str & to_route

str() 就是之前的 Str::of()，可以做一些字串的操作。

https://laravel.com/docs/9.x/redirects#redirecting-named-routes
之前 Redirect to Named Route 的 sample code

return redirect()->route('profile', ['id' => 1]);

Laravel 9 新寫法的 sample code

return to_route('users.show', ['user' => 1]);

甚至可以指定 HTTP status code 和 response header

return to_route('users.show', ['user' => 1], 302, ['X-Framework' => 'Laravel']);

結語

這次 Laravel 9 主要是底層語言與模組的更新，程式的寫法上更加簡潔漂亮。另外，如果你的環境是 PHP 8.1 以上，PHP 8.1 enum 的用法也可以參考一下。

這次 Laravel 的更新，可能對有軟體工程基礎，對 Laravel 又有經驗的讀者，會比較有參考價值。

初探 Alpine.js — Laravel 預設的前端框架從 Vue.js 改為使用 Alpine.js

Larry — Sun, 30 May 2021 14:19:26 +0000

這幾年到目前 (2021年5月) 為止，最受歡迎的 JavaScript framework 主要還是三大家：Angular, React, Vue.js。

Laravel 從 5.x 版開始用 Vue.js 當預設的前端框架，Laravel 5 的那一段時間，開發者數量成長很快，相信也間接推動了 Vue.js 的普及。

接下來 Laravel 6 和 7 是使用一個 laravel/ui 套件來建構前端，laravel/ui 建構時可以選擇 bootstrap, vue, react 三選一。納入更多選擇，也可以解讀為 Laravel 漸漸脫離 Vue.js 的相依性。

目前 (2021年5月) Laravel 8 則是用一個 laravel/breeze 套件來建構前端，laravel/breeze 預設是使用 Alpine.js，但也可以指定要用 vue 或 react。

所以可以看出來，從 Laravel 5 預設是 Vue.js，到 vue 只是一個選項，到 Laravel 8 預設使用 Alpine.js。就 Laravel 的態度而言，整個趨勢是從 Vue.js 轉到 Alpine.js。

本篇我們就來聊一下 Alpine.js

Alpine.js 是一個相對非常年輕的前端框架，1.0 版是 2019 年 12 月釋出。作者是 Caleb Porzio，他是 Laravel 開發者和 Laravel 框架本身的開發者。所以他當時也是用 Vue.js，後來才創作了 Laravel Livewire 及 Alpine.js。

因爲作者 Caleb Porzio 的背景是 Laravel 開發者，想要簡化前端的工作，所以 Alpine.js 的創作精神就是輕量、簡化。Alpine.js 的檔案size很小，安裝及使用簡單，不會因為簡單功能就需要寫一堆 JS code，更沒有編譯 TypeScript 等事情。

Alpine.js 官方網頁 https://github.com/alpinejs/alpine

Alpine.js 的使用首先用 x-data 宣告一個 component scope。x-data 裡宣告的變數，在這個 component scope 裡都能存取。

...

用 x-text, x-html 可以將變數填入DOM。x-html 因為內容可以是 html，沒有 escape，所以使用者編輯的內容，不要使用 x-html

使用 x-on:[event] 可以設定 event handler，例如 x-on:click，也可以縮寫成 @click


// 縮寫

使用 x-model 可以雙向綁定 DOM 上顯示的值和 component scope 裡變數的值

x-if 可以達成 if else 的功能，注意 x-if 需要搭配