> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# laravel/symfony-on-cloud — 在 Laravel Cloud 上執行 Symfony 應用

> Laravel 官方新 repository 調查。解說可讓 Symfony Messenger 的託管佇列在 Laravel Cloud 上使用的官方 Symfony bundle。

<Info>
  本文為 2026 年 6 月時點的初步調查。`laravel/symfony-on-cloud` 是開發階段的 repository，未來預計會追加更多功能。
</Info>

## 什麼是 laravel/symfony-on-cloud

[laravel/symfony-on-cloud](https://github.com/laravel/symfony-on-cloud) 是**為 Symfony 應用程式帶來 Laravel Cloud 功能**的官方 Symfony bundle。這是 2026 年 6 月 27 日發佈的非常新的 repository。

```mermaid theme={null}
flowchart LR
    A["Symfony 應用"] --> B["laravel/symfony-on-cloud<br>Bundle"]
    B --> C["Laravel Cloud<br>託管佇列"]
    C --> D["AWS SQS"]
    C --> E["Cloud 儀表板<br>指標顯示"]
```

Laravel Cloud 過去是 Laravel 應用專用的平台，透過此套件，**Symfony 開發者也可以運用 Laravel Cloud 的基礎架構（如託管佇列等）**。

首個功能是**使用 Symfony Messenger 的託管佇列**。README 中提到「more Laravel Cloud capabilities will follow」，未來還會追加佇列以外的功能。

## 安裝

```bash theme={null}
composer require laravel/symfony-on-cloud
```

接著在 `config/bundles.php` 註冊該 bundle（Symfony Flex 的 recipe 尚未支援，因此需要手動加入）。

```php theme={null}
return [
    // ...
    Laravel\Cloud\Symfony\LaravelCloudBundle::class => ['all' => true],
];
```

## 託管佇列

### 基本設定

Bundle 提供了名為 `cloud` 的預先建立 transport。在 Laravel Cloud 環境中會自動注入連線設定，因此不需要手動設定 DSN。

```yaml theme={null}
# config/packages/messenger.yaml
framework:
    messenger:
        routing:
            '*': cloud
```

<Tip>
  將既有的 Symfony Messenger 應用遷移到 Laravel Cloud 也很簡單。Cloud 會自動注入 `MESSENGER_TRANSPORT_DSN=laravel-cloud://managed-queue`，因此原本使用 `async` transport（`dsn: '%env(MESSENGER_TRANSPORT_DSN)%'`）的應用可完全不改程式碼運作。
</Tip>

### 多個佇列

在 Laravel Cloud 環境中可建立多個託管佇列（例如 `default` 與 `critical`）。每個佇列以獨立的 SQS 佇列與 worker 運作。使用 `CloudQueueStamp` 可將訊息 dispatch 到特定佇列。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;
use Symfony\Component\Messenger\MessageBusInterface;

$bus->dispatch(new ProcessReport($report), [new CloudQueueStamp('critical')]);
```

未指定 stamp 就 dispatch 的話，會傳送到預設佇列。

### FIFO 佇列

名稱以 `.fifo` 結尾的託管佇列會被視為 [FIFO 佇列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html)。訊息會以嚴格順序傳遞，並排除重複。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

$bus->dispatch(new ProcessOrder($order), [new CloudQueueStamp('orders.fifo')]);
```

預設情況下，group ID 會自動設為佇列名稱，deduplication ID 則自動設為唯一值。若需更精細的控制，可加上 `CloudFifoStamp`。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudFifoStamp;
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

$bus->dispatch(new ProcessOrder($order), [
    new CloudQueueStamp('orders.fifo'),
    new CloudFifoStamp(
        messageGroupId: 'customer-'.$order->customerId,
        messageDeduplicationId: 'order-'.$order->id,
    ),
]);
```

### 公平佇列（Fair Queue）

[SQS 公平佇列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fair-queues.html) 是即使某個 tenant 投入大量 job，也不會壓迫其他 tenant 的機制。在標準佇列中加上 message group ID 後，SQS 就會公平地在 tenant 之間分配處理能力。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudMessageGroupStamp;
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

$bus->dispatch(new ProcessOrder($order), [
    new CloudQueueStamp('orders'),
    new CloudMessageGroupStamp('customer-'.$order->customerId),
]);
```

<Info>
  `CloudMessageGroupStamp` **僅適用於標準佇列**，FIFO 佇列無法使用。FIFO 佇列中的 group 指定請使用 `CloudFifoStamp`。
</Info>

### 延遲

使用 `DelayStamp` 可對標準佇列設定傳送延遲。不過受限於 SQS 規格，**最多為 15 分鐘**。超過 15 分鐘會發生錯誤（不會靜默地在 15 分鐘後執行）。

FIFO 佇列不支援延遲，因此 `DelayStamp` 本身會產生錯誤。

### 重試

Handler 失敗時，bundle 會將訊息返回 SQS，透過 visibility timeout 進行重新傳遞。這樣可以等到 SQS 的 visibility timeout 上限（**12 小時**），而非傳送限制（15 分鐘）。

重試設定使用 Symfony Messenger 標準的 `retry_strategy`。

```yaml theme={null}
# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            cloud:
                retry_strategy:
                    max_retries: 3    # 重試 3 次（共執行 4 次）
                    delay: 1000       # 初始 backoff（毫秒）
                    multiplier: 2     # backoff 倍率
                    max_delay: 0      # 無上限（SQS 12 小時限制生效）
```

實作 `UnrecoverableExceptionInterface` 的例外會不重試，立即記錄為失敗。

## 本機開發

`cloud` transport 可以在應用中覆蓋。本機使用 `sync://` 時，job 會立即同步執行。

```yaml theme={null}
# config/packages/messenger.yaml
when@dev:
    framework:
        messenger:
            transports:
                cloud: 'sync://'
```

若要完全停用該功能，可設定 `laravel_cloud.queue.enabled: false`。

## 總結

`laravel/symfony-on-cloud` 是讓 Symfony 應用也可運用 Laravel Cloud 基礎架構的官方 bundle。目前實作了**託管佇列**，備齊了與 Symfony Messenger 整合、多重佇列、FIFO / 公平佇列、重試設定等實用功能。

| Stamp                    | 用途                    |
| ------------------------ | --------------------- |
| `CloudQueueStamp`        | 分派到特定佇列               |
| `CloudFifoStamp`         | FIFO 佇列的順序 / 去重控制     |
| `CloudMessageGroupStamp` | 標準佇列的公平分配（tenant key） |

根據官方 README，未來會追加佇列以外的 Laravel Cloud 功能。若在 Laravel Cloud 上運營 Symfony 應用的情境增加，這將是非常有價值的套件。

## 相關連結

<CardGroup cols={2}>
  <Card title="laravel/symfony-on-cloud" icon="github" href="https://github.com/laravel/symfony-on-cloud">
    官方 repository、README
  </Card>

  <Card title="Laravel Cloud" icon="cloud" href="https://laravel.com/cloud">
    Laravel Cloud 官方網站
  </Card>

  <Card title="Symfony Messenger" icon="envelope" href="https://symfony.com/doc/current/messenger.html">
    Symfony Messenger 官方文件
  </Card>

  <Card title="Laravel Cloud 文件" icon="book" href="https://cloud.laravel.com/docs/intro">
    Laravel Cloud 詳細文件
  </Card>
</CardGroup>


## Related topics

- [2026 年 6 月 Laravel 更新](/zh-TW/blog/changelog/202606.md)
- [Laravel Cloud Hibernation（自動休眠）](/zh-TW/blog/laravel-cloud-hibernation.md)
- [Laravel Cloud CLI — 從終端機操作 Laravel Cloud](/zh-TW/blog/laravel-cloud-cli.md)
- [Laravel Octane](/zh-TW/octane.md)
- [Laravel Cloud — Laravel 專用 PaaS 全貌](/zh-TW/blog/laravel-cloud.md)