Collection 的 Higher Order Messages

// 一般的寫法
$names = $users->map(fn ($user) => $user->name);

// 使用 Higher Order Messages 的寫法
$names = $users->map->name;

// src/Illuminate/Collections/Traits/EnumeratesValues.php
public function __get($key)
{
    if (! in_array($key, static::$proxies)) {
        throw new Exception("Property [{$key}] does not exist on this collection instance.");
    }

    return new HigherOrderCollectionProxy($this, $key);
}

// src/Illuminate/Collections/HigherOrderCollectionProxy.php
public function __get($key)
{
    return $this->collection->{$this->method}(function ($value) use ($key) {
        return is_array($value) ? $value[$key] : $value->{$key};
    });
}

$users->map(fn ($user) => $user->name);

public function __call($method, $parameters)
{
    return $this->collection->{$this->method}(function ($value) use ($method, $parameters) {
        return is_string($value)
            ? $value::{$method}(...$parameters)
            : $value->{$method}(...$parameters);
    });
}

$users->each(fn ($user) => $user->activate());

protected static $proxies = [
    'average', 'avg',
    'contains', 'doesntContain', 'some',
    'each', 'every',
    'filter', 'reject',
    'first', 'last',
    'flatMap', 'map',
    'groupBy', 'keyBy',
    'hasMany', 'hasSole',
    'max', 'min', 'sum', 'percentage',
    'partition',
    'skipUntil', 'skipWhile',
    'sortBy', 'sortByDesc',
    'takeUntil', 'takeWhile',
    'unique',
    'unless', 'until', 'when',
];

Collection::proxy('myCustomMethod');

$users = User::with('posts')->get();

// 方法呼叫：更新每個使用者的狀態
$users->each->markAsVerified();

// 屬性存取：僅取出名稱
$names = $users->map->name;

// 傳入引數的方法
$users->each->sendPasswordReset('zh-TW');

// 寄送 mail
$users->each->notify(new WelcomeNotification);

$activeUsers = $users->filter->isActive();

// 只保留 isActive() 為 true 的使用者
// 等同於 $users->filter(fn ($user) => $user->isActive())

$inactiveUsers = $users->reject->isActive();

// 對每個使用者的 post_count 屬性求和
$totalPosts = $users->sum->post_count;

// 對每個使用者的 score 取最大值
$highestScore = $users->max->score;

// 對每個使用者的 age 取平均
$averageAge = $users->avg->age;

// 依 role 屬性分組
$grouped = $users->groupBy->role;

// 依 name 屬性升冪排序
$sorted = $users->sortBy->name;

// 依 created_at 屬性降冪排序
$sorted = $users->sortByDesc->created_at;

// 展開每個使用者的 posts 關聯彙整為單一 collection
$posts = $users->flatMap->posts;

// 確認是否全員為管理員
$allAdmins = $users->every->isAdmin();

// 確認是否有任一位為 active
$hasActive = $users->contains->isActive();

// 確認是否全員屬於特定 plan
$allPro = $users->every->hasPlan('pro');

$names = collect(['alice', 'bob', 'charlie']);

// 對字串 collection 使用 closure 較為明確
$upper = $names->map(fn ($name) => strtoupper($name));
// ['ALICE', 'BOB', 'CHARLIE']

// Higher Order Messages：適合單純的屬性取得、方法呼叫
$emails = $users->map->email;
$users->each->sendWelcomeMail();
$admins = $users->filter->isAdmin();

// Closure：適合需要複雜邏輯或引數的情境
$formatted = $users->map(function ($user) {
    return "{$user->name} <{$user->email}>";
});

$filtered = $users->filter(function ($user) use ($minAge, $role) {
    return $user->age >= $minAge && $user->role === $role;
});

namespace App\Providers;

use Illuminate\Support\Collection;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // 將自訂 macro 加入 proxy 對象
        Collection::macro('active', function () {
            return $this->filter(fn ($item) => $item->isActive());
        });

        Collection::proxy('active');
    }
}

// 註冊後可作為 Higher Order Messages 使用
$activeUsers = $users->active;