> ## 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 — Symfony 앱을 Laravel Cloud에서 동작시키기

> Laravel 공식의 새 리포지토리 조사. Symfony Messenger의 매니지드 큐를 Laravel Cloud 상에서 이용할 수 있는 공식 Symfony 번들을 설명합니다.

<Info>
  이 글은 2026년 6월 시점의 초기 조사입니다. `laravel/symfony-on-cloud`는 개발 단계의 리포지토리로, 앞으로 기능이 추가될 예정입니다.
</Info>

## laravel/symfony-on-cloud란

[laravel/symfony-on-cloud](https://github.com/laravel/symfony-on-cloud)는 **Symfony 애플리케이션에 Laravel Cloud의 기능을 가져다 주는** 공식 Symfony 번들입니다. 2026년 6월 27일에 공개된 매우 새로운 리포지토리입니다.

```mermaid theme={null}
flowchart LR
    A["Symfony 앱"] --> B["laravel/symfony-on-cloud<br>번들"]
    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`에 번들을 등록합니다 (Symfony Flex의 레시피는 미대응이므로 수동으로 추가합니다).

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

## 매니지드 큐

### 기본 설정

번들은 `cloud`라는 이름의 기제 트랜스포트를 제공합니다. 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` 트랜스포트(`dsn: '%env(MESSENGER_TRANSPORT_DSN)%'`)를 그대로 사용하고 있는 앱은 코드 변경 없이 동작합니다.
</Tip>

### 여러 큐

Laravel Cloud 환경에서는 여러 매니지드 큐(예: `default`와 `critical`)를 생성할 수 있습니다. 각 큐는 독립된 SQS 큐와 워커로 동작합니다. `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')]);
```

스탬프 없이 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')]);
```

기본으로는 그룹 ID에 큐 이름, 중복 배제 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,
    ),
]);
```

### 페어 큐

[SQS 페어 큐](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fair-queues.html)는 하나의 테넌트가 대량의 잡을 투입해도 다른 테넌트를 압박하지 않는 구조입니다. 표준 큐에서 메시지 그룹 ID를 부여함으로써, SQS가 테넌트 간에 처리 능력을 공평하게 분배합니다.

```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 큐에서의 그룹 지정은 `CloudFifoStamp`를 사용합니다.
</Info>

### 지연

`DelayStamp`를 사용하면 표준 큐에 송신 지연을 설정할 수 있습니다. 다만 SQS의 사양에 의해 **최대 15분**의 제한이 있습니다. 15분을 넘으면 오류가 됩니다 (사일런트하게 15분에 실행되는 일은 없습니다).

FIFO 큐에서는 지연이 지원되지 않으므로, `DelayStamp` 자체가 오류가 됩니다.

### 리트라이

핸들러가 실패한 경우, 번들은 메시지를 SQS로 되돌려 가시성 타임아웃 경유로 재배신합니다. 송신 제한(15분)이 아니라 SQS의 가시성 타임아웃 상한(**12시간**)까지 대기할 수 있습니다.

리트라이 설정은 Symfony Messenger 표준의 `retry_strategy`를 사용합니다.

```yaml theme={null}
# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            cloud:
                retry_strategy:
                    max_retries: 3    # 3회 리트라이 (계 4회 실행)
                    delay: 1000       # 최초의 백오프 (밀리초)
                    multiplier: 2     # 백오프 배율
                    max_delay: 0      # 상한 없음 (SQS의 12시간 제한이 유효)
```

`UnrecoverableExceptionInterface`를 구현한 예외는 리트라이 없이 즉시 실패로 기록됩니다.

## 로컬 개발

`cloud` 트랜스포트는 앱에서 덮어쓸 수 있습니다. 로컬에서는 `sync://`를 사용하면 잡이 즉시 동기 실행됩니다.

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

기능을 완전히 비활성화하려면 `laravel_cloud.queue.enabled: false`를 설정합니다.

## 정리

`laravel/symfony-on-cloud`는 Laravel Cloud의 인프라를 Symfony 앱에서도 활용할 수 있도록 하는 공식 번들입니다. 우선 **매니지드 큐**가 구현되어 있으며, Symfony Messenger와의 통합, 여러 큐, FIFO/페어 큐, 리트라이 설정 등 실용적인 기능이 갖추어져 있습니다.

| 스탬프                      | 용도                    |
| ------------------------ | --------------------- |
| `CloudQueueStamp`        | 특정 큐로 dispatch        |
| `CloudFifoStamp`         | FIFO 큐의 순서 · 중복 배제 제어 |
| `CloudMessageGroupStamp` | 표준 큐의 페어 분배 (테넌트 키)   |

공식 README에 따르면 앞으로도 큐 이외의 Laravel Cloud 기능이 추가될 예정입니다. Symfony 앱을 Laravel Cloud에서 운용하는 케이스가 늘면 매우 가치 있는 패키지가 될 것으로 보입니다.

## 관련 링크

<CardGroup cols={2}>
  <Card title="laravel/symfony-on-cloud" icon="github" href="https://github.com/laravel/symfony-on-cloud">
    공식 리포지토리 · 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

- [Laravel 8에서 9로의 업그레이드](/ko/blog/upgrade-8-to-9.md)
- [Laravel Cloud Hibernation (자동 휴면)](/ko/blog/laravel-cloud-hibernation.md)
- [Laravel Passport(OAuth2 서버 구현)](/ko/passport.md)
- [Laravel Sail](/ko/sail.md)
- [Labeler](/ko/packages/laravel-bluesky/labeler.md)