laravel/symfony-on-cloud

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

laravel/symfony-on-cloud란

laravel/symfony-on-cloud는 Symfony 애플리케이션에 Laravel Cloud의 기능을 가져다 주는 공식 Symfony 번들입니다. 2026년 6월 27일에 공개된 매우 새로운 리포지토리입니다. Laravel Cloud는 지금까지 Laravel 애플리케이션 전용 플랫폼이었지만, 이 패키지에 의해 Symfony 개발자도 Laravel Cloud의 인프라(매니지드 큐 등)를 활용할 수 있게 됩니다. 첫 번째 기능은 Symfony Messenger를 사용한 매니지드 큐입니다. README에는 “more Laravel Cloud capabilities will follow”라고 되어 있어, 앞으로도 큐 이외의 기능이 추가될 예정입니다.

설치

composer require laravel/symfony-on-cloud

다음으로 config/bundles.php에 번들을 등록합니다 (Symfony Flex의 레시피는 미대응이므로 수동으로 추가합니다).

return [
    // ...
    Laravel\Cloud\Symfony\LaravelCloudBundle::class => ['all' => true],
];

매니지드 큐

기본 설정

번들은 cloud라는 이름의 기제 트랜스포트를 제공합니다. Laravel Cloud 환경에서는 접속 설정을 자동으로 주입하므로, DSN을 수동 설정할 필요가 없습니다.

# config/packages/messenger.yaml
framework:
    messenger:
        routing:
            '*': cloud

기존 Symfony Messenger 앱을 Laravel Cloud로 마이그레이션하는 경우도 간단합니다. Cloud가 MESSENGER_TRANSPORT_DSN=laravel-cloud://managed-queue를 자동 주입하므로, 기존의 async 트랜스포트(dsn: '%env(MESSENGER_TRANSPORT_DSN)%')를 그대로 사용하고 있는 앱은 코드 변경 없이 동작합니다.

여러 큐

Laravel Cloud 환경에서는 여러 매니지드 큐(예: default와 critical)를 생성할 수 있습니다. 각 큐는 독립된 SQS 큐와 워커로 동작합니다. CloudQueueStamp를 사용하여 특정 큐로 dispatch합니다.

use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;
use Symfony\Component\Messenger\MessageBusInterface;

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

스탬프 없이 dispatch하면 기본 큐로 보내집니다.

FIFO 큐

이름이 .fifo로 끝나는 매니지드 큐는 FIFO 큐로 취급됩니다. 메시지가 엄격한 순서로 배신되고, 중복이 배제됩니다.

use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

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

기본으로는 그룹 ID에 큐 이름, 중복 배제 ID에 고유 값이 자동 설정됩니다. 보다 세밀한 제어가 필요한 경우는 CloudFifoStamp를 추가합니다.

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 페어 큐는 하나의 테넌트가 대량의 잡을 투입해도 다른 테넌트를 압박하지 않는 구조입니다. 표준 큐에서 메시지 그룹 ID를 부여함으로써, SQS가 테넌트 간에 처리 능력을 공평하게 분배합니다.

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),
]);

CloudMessageGroupStamp는 표준 큐 전용이며 FIFO 큐에서는 사용할 수 없습니다. FIFO 큐에서의 그룹 지정은 CloudFifoStamp를 사용합니다.

지연

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

리트라이

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

# 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://를 사용하면 잡이 즉시 동기 실행됩니다.

# 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에서 운용하는 케이스가 늘면 매우 가치 있는 패키지가 될 것으로 보입니다.

공식 리포지토리 · README

Laravel Cloud

Laravel Cloud의 공식 사이트

Symfony Messenger

Symfony Messenger 공식 문서

Laravel Cloud 문서

Laravel Cloud 상세 문서