Sendgo Notification 패키지 분석 — 한국 Laravel 개발자 가이드

요약

techigh/sendgo-notification은 Laravel 프로젝트에서 SendGo.io API를 통해 카카오 알림톡, 친구톡, SMS/LMS/MMS를 전송할 수 있는 MIT 라이선스 오픈소스 패키지입니다. Laravel 8.x~11.x 및 PHP 8.2+를 지원하며, Laravel 표준 Notification 채널 패턴을 따르기 때문에 기존 알림 시스템과 자연스럽게 통합됩니다. 국내 서비스에서 빠질 수 없는 카카오톡 채널 메시지와 SMS 발송을 notify() 한 줄로 처리할 수 있다는 점이 핵심 가치입니다.

---

핵심 내용

지원 채널 및 메시지 유형

• 알림톡 (AlimTalk): 사전 승인된 템플릿 기반 공식 비즈니스 메시지. 발송 실패 시 SMS 자동 대체(replaceSms) 옵션 내장
• 친구톡 (FriendTalk): 카카오톡 채널 친구 대상 자유 형식 메시지. 텍스트(FT), 이미지(FI), 와이드 이미지(FW), 캐러셀(FC/FA) 등 8가지 타입 지원
• SMS / LMS / MMS: 단문·장문·멀티미디어 문자. MMS는 파일 경로 배열로 최대 3개 첨부 가능

Laravel Notification 채널 통합

표준 Notification 클래스의 via() 메서드에 AlimTalkChannel::class, FriendTalkChannel::class, SmsChannel::class를 반환하는 방식으로 동작합니다. 기존 Laravel 알림 아키텍처를 그대로 유지할 수 있습니다.

to() vs toMany() — 주의해야 할 설계 제약

패키지의 가장 중요한 설계 제약 중 하나입니다.

대량 발송이 필요한 경우 Sms::class, AlimTalk::class, FriendTalk::class 서비스를 직접 app() 바인딩으로 호출해야 합니다.

API v1 / v2 동시 지원 및 마이그레이션

.env 한 줄 변경만으로 v1→v2 전환이 가능합니다.

v2 전환 시 달라지는 점:

주의: Notification 코드 자체는 변경이 필요 없으나, v2 에러 코드 체계가 달라지므로 SendGoException::context()['error_code'] 기반 예외 처리 로직은 사전 검토가 필요합니다.

예외 처리 구조

모든 발송 실패는 SendGoException으로 통일되며, context() 메서드로 상세 컨텍스트를 확인할 수 있습니다.

에러 코드 예시 (인증 관련):

큐 비동기 발송

ShouldQueue 인터페이스 구현으로 Laravel 큐 시스템과 즉시 연동됩니다. 다중 워커 환경에서는 토큰 캐시 공유를 위해 반드시 Redis 또는 Database 캐시 드라이버 사용이 권장됩니다.

---

한국 Laravel 개발자에게 미치는 영향

호환성

• PHP: 8.2 이상 필수. PHP 8.1 이하 환경은 업그레이드가 선행되어야 합니다.
• Laravel: 8.x~11.x 지원. Laravel 12.x 지원 여부는 README 기준으로 명시되지 않았으므로, 해당 버전 사용자는 별도 테스트 후 적용을 권장합니다.
• Composer 패키지명은 techigh/sendgo-notification이나, README 배지 기준 버전은 1.2.0, Packagist 메타데이터 기준 버전은 1.1.0으로 불일치가 있습니다. 설치 전 composer show techigh/sendgo-notification으로 실제 배포 버전을 반드시 확인하세요.

마이그레이션 난이도

• 기존에 자체 구현한 카카오 알림톡/SMS 발송 로직을 이 패키지로 교체하는 경우, Notification 클래스 재작성이 필요하지만 Laravel 표준 패턴을 따르므로 난이도는 낮은 편입니다.
• toMany() 제약으로 인해 루프 기반 대량 발송 코드를 직접 서비스 호출 방식으로 리팩토링해야 하는 경우가 발생할 수 있습니다.

로컬 개발 환경 (Valet, Sail, Docker)

• Laravel Sail: SENDGO_* 환경 변수를 .env에 추가하면 별도 설정 없이 동작합니다. 큐 워커는 sail artisan queue:work로 실행 가능합니다.
• Laravel Valet: MMS 파일 첨부 시 storage_path() 기반 파일 경로가 Valet 로컬 환경에서도 정상 동작하는지 확인하세요.
• Docker 멀티 컨테이너 환경: 토큰 캐시 공유 문제가 발생할 수 있으므로 Redis 캐시 드라이버 설정이 필수입니다.

보안 고려사항

• SENDGO_ACCESS_KEY, SENDGO_SECRET_KEY는 반드시 .env에만 보관하고 버전 관리에서 제외해야 합니다.
• CI/CD 파이프라인에서는 GitHub Actions Secrets, AWS Parameter Store 등 비밀 관리 도구를 통해 주입하는 것을 권장합니다.

---

실무 체크리스트

로컬 환경

• PHP 버전 확인: php -v → 8.2 이상인지 확인
• composer require techigh/sendgo-notification 설치
• composer show techigh/sendgo-notification으로 실제 설치 버전 확인 (README 버전과 불일치 여부 주의)
• php artisan vendor:publish --tag=sendgo로 설정 파일 발행
• .env에 SENDGO_URL, SENDGO_ACCESS_KEY, SENDGO_SECRET_KEY, SENDGO_SENDER_KEY, SENDGO_KAKAO_SENDER_KEY, SENDGO_API_VERSION 추가
• 카카오 알림톡 사용 시 SendGo 콘솔에서 템플릿 코드 사전 승인 완료 여부 확인
• SmsMessage, AlimTalkMessage, FriendTalkMessage 중 필요한 채널로 테스트 Notification 클래스 작성 및 발송 테스트

스테이징 환경

• SENDGO_API_VERSION=v1 또는 v2 명시적으로 설정
• SendGoException 예외 처리 블록에서 error_code, status, body 로깅 동작 확인
• toMany() 사용 코드가 Notification 채널이 아닌 직접 서비스 호출 방식인지 재확인
• 큐 사용 시 CACHE_DRIVER=redis, QUEUE_CONNECTION=redis 설정 후 다중 워커 환경에서 토큰 캐시 공유 테스트
• replaceSms('Y') 설정 시 smsTitle, smsContent 누락 여부 확인

프로덕션 환경

• API 키를 비밀 관리 도구(AWS SSM, Vault 등)를 통해 주입, .env 직접 노출 방지
• 큐 워커 --queue=notifications 옵션으로 알림 전용 큐 분리 운영 고려
• $tries, $backoff 값을 서비스 특성에 맞게 조정 (예: 알림톡 3회 재시도, 간격 10초)
• failed() 메서드에서 최종 실패 시 Slack, 사내 모니터링 시스템 등으로 알림 전송 구현
• v2로 전환 예정인 경우 스테이징에서 SENDGO_API_VERSION=v2 전환 후 에러 코드 분기 로직 검증 완료 후 프로덕션 적용
• Laravel 12.x 사용 중인 경우 공식 지원 여부 확인 전까지 별도 통합 테스트 수행

⚠️ 편집자 주: README 상의 버전 배지(1.2.0)와 Packagist 메타데이터(1.1.0) 간 불일치가 확인되었습니다. 발행 전 패키지 최신 릴리스 버전을 재확인하여 기사 내용을 업데이트하세요.