English
업그레이드

PHP 버전 호환성과 안전한 업그레이드 계획

8분 분량 업데이트

요약

패치 릴리스는 일상적인 작업이지만, 브랜치 업그레이드에는 계획이 필요합니다. 지원 기간이 긴 대상을 선택하고, Composer, PHPCompatibility, Rector로 의존성과 코드를 점검한 뒤, 백업과 롤백 경로를 갖춘 스테이징에서 테스트하고 운영 환경을 단계적으로 업그레이드하십시오.

패치 업그레이드와 브랜치 업그레이드

PHP 업그레이드는 두 종류가 있으며, 위험 수준이 크게 다릅니다.

업그레이드 유형 예시 일반적인 위험 빈도
같은 브랜치 내 패치 릴리스 8.3.35 → 8.3.36 낮음. 수정 사항만 포함 릴리스가 나올 때마다
새 브랜치로의 마이너 버전 8.2 → 8.4 보통. 사용 중단(deprecation), 기능 제거, 동작 변경 1~4년마다
메이저 버전 7.4 → 8.x 높음. 상당한 언어 변경 드묾

패치 릴리스는 일상적인 유지 보수로서 신속하게 적용해야 합니다. 이 가이드는 두 번째와 세 번째 행, 즉 애플리케이션을 망가뜨리지 않고 새 브랜치로 이동하는 방법을 다룹니다.

1단계: 대상 브랜치 선택하기

프레임워크, CMS, 핵심 의존성이 지원하는 가장 최신 브랜치를 선택하십시오. 그래야 지원 기간이 가장 길고, 장기적으로 업그레이드 횟수도 가장 적습니다.

2026년 10월 기준:

브랜치 보안 지원 종료일 비고
8.5 2029-12-31 최신 안정 브랜치, 활성 지원은 2027-12-31까지
8.4 2028-12-31 활성 지원은 2026-12-31까지
8.3 2027-12-31 보안 수정만 제공
8.2 2026-12-31 보안 수정만 제공. 몇 주 후 종료
8.6 아직 릴리스되지 않음 릴리스 후보(RC). 운영 환경에서 사용하지 마십시오

2026년 말에 8.2나 8.3으로 업그레이드하면 곧이어 또 다른 업그레이드를 계획해야 합니다. 8.1 이하를 사용 중이라면 이미 지원되지 않는 브랜치에 있는 것이며, 이 브랜치들은 2026-10-21에 패치된 치명적인 문제인 CVE-2026-109618과 CVE-2026-109619에 대한 수정을 받지 못했습니다. 전체 일정은 PHP 보안 지원 수명 주기를 참고하십시오.

8.1에서 8.4로 바로 가는 것처럼 브랜치를 건너뛰는 것은 일반적입니다. 다만 사용 중단과 기능 제거가 누적되므로, 건너뛰는 모든 브랜치의 마이그레이션 문서를 읽어야 합니다.

2단계: 마이그레이션 가이드 읽기

PHP 매뉴얼은 마이너 버전마다 하위 호환성이 깨지는 변경, 사용 중단된 기능, 새 함수를 정리한 마이그레이션 부록을 제공합니다. 현재 버전과 대상 버전 사이의 각 브랜치에 대해 다음을 읽으십시오.

  • 하위 호환성이 깨지는 변경(Backward incompatible changes): 동작하지 않게 될 것들
  • 사용 중단된 기능(Deprecated features): 아직 동작하지만 사용 중단 알림을 출력하며 나중에 제거될 가능성이 높은 것들
  • 변경된 함수와 제거된 확장 기능

코드베이스에 영향을 줄 만한 항목을 짧은 목록으로 정리하십시오. 개별 수정 사항을 확인할 때는 PHP 8 ChangeLog가 유용합니다.

3단계: Composer로 의존성 확인하기

대부분의 호환성 문제는 직접 작성한 코드가 아니라 의존성에서 발생합니다. Composer를 사용한다면 잠금(lock)된 패키지가 대상 PHP 버전을 허용하는지 확인하십시오.

먼저 현재 상태를 확인합니다.

composer check-platform-reqs

이 명령은 설치된 패키지가 요구하는 PHP 버전 및 확장 기능을 현재 환경이 제공하는 것과 비교합니다. 대상 환경(새 PHP 버전이 설치된 컨테이너나 스테이징 서버) 안에서 실행해 무엇이 실패하는지 확인하십시오.

서버를 변경하지 않고 의존성 트리가 대상 버전에서 해석되는지 테스트하려면, 플랫폼 버전을 임시로 설정한 뒤 시험 실행(dry run)을 합니다.

composer config platform.php 8.4.27
composer update --dry-run

Composer는 해당 PHP 버전에 설치할 수 없는 패키지를 알려 줍니다. 유지할 생각이 없다면 이후 platform 설정을 되돌리거나, 로컬 설치가 운영 환경과 일치하도록 운영 버전으로 의도적으로 설정해 두십시오.

다음도 확인하십시오.

composer outdated --direct

여러 메이저 버전 뒤처진 패키지가 흔한 걸림돌입니다. 현재 PHP 버전에서 먼저, 작게 나눈 별도의 변경으로 업그레이드하십시오.

4단계: 직접 작성한 코드 스캔하기

PHPCompatibility

PHPCompatibility는 PHP_CodeSniffer용 규칙 모음으로, 제거된 함수나 변경된 문법처럼 지정한 PHP 버전 범위와 호환되지 않는 코드를 찾아냅니다.

composer require --dev phpcompatibility/php-compatibility
vendor/bin/phpcs -p src/ --standard=PHPCompatibility --runtime-set testVersion 8.4-

testVersion 8.4-는 “8.4 이상”을 의미합니다. 최신 PHP 버전에 대한 탐지 여부는 사용하는 릴리스에 따라 달라지므로, 설치하는 릴리스가 어떤 PHP 버전을 다루는지 프로젝트의 README를 확인하십시오. 정적 분석으로 모든 것을 잡아낼 수는 없으며, 특히 런타임 값에 따라 달라지는 동작은 탐지하기 어렵습니다.

Rector

Rector는 업그레이드와 관련된 많은 변경을 자동으로 적용할 수 있습니다. 최소 구성은 다음과 같습니다.

<?php
// rector.php
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withPhpSets(php84: true);

항상 먼저 미리 보기를 실행하십시오.

vendor/bin/rector process --dry-run

제안된 diff를 검토하고, 전용 브랜치에 적용한 뒤, 테스트를 실행하십시오. 자동 리팩터링은 빠르지만 완벽하지는 않습니다.

정적 분석과 사용 중단 로그

PHPStan이나 Psalm을 사용한다면 대상 버전에 맞게 구성해 실행하십시오. 현재 운영 버전에서는 사용 중단 로그를 활성화해 코드가 이미 발생시키고 있는 알림을 확인하십시오.

; php.ini on staging
error_reporting = E_ALL
log_errors = On
display_errors = Off

5단계: 운영 환경과 일치하는 스테이징 환경 구축하기

구성이 다른 노트북에서 테스트해서는 증명되는 것이 거의 없습니다. 스테이징(staging)은 다음 항목에서 운영 환경과 일치해야 합니다.

  • PHP 버전, SAPI(FPM 또는 Apache 모듈), 로드된 확장 기능(php -m)
  • php.ini 설정, 특히 memory_limit, max_execution_time, 업로드 제한
  • 웹 서버, 데이터베이스 버전, cron 작업

개인정보 보호 규정이 허용한다면 운영 데이터를 복사하고, 그렇지 않다면 현실적인 익명화 데이터셋을 사용하십시오. 그런 다음 다음을 실행합니다.

  1. 대상 버전에서 자동화된 테스트 스위트
  2. 핵심 경로 수동 점검: 로그인, 결제, 폼, 파일 업로드, 관리자 화면, 예약 작업, 이메일 발송
  3. 백그라운드 워커와 CLI 스크립트(웹 서버와 다른 바이너리로 실행되는 경우가 많음)

모든 오류와 사용 중단 알림을 기록하고, 운영 환경 일정을 잡기 전에 치명적 오류(fatal error)를 수정하십시오.

6단계: 배포 준비하기

  1. 파일과 데이터베이스를 백업하고, 복원할 수 있는지 확인합니다.
  2. 이전 버전을 설치된 상태로 유지합니다. 대부분의 서버에서 여러 PHP 버전이 공존할 수 있습니다. 되돌리는 작업은 재설치가 아니라 설정 변경이어야 합니다.
  3. 변경할 정확한 패널 설정이나 설정 행을 포함해 롤백 절차를 문서로 작성합니다.
  4. 트래픽이 적은 시간대를 선택하고, 애플리케이션을 잘 아는 사람이 대기하도록 합니다.
  5. 서버나 사이트가 여러 개라면 단계적으로 업그레이드합니다. 먼저 서버 한 대나 위험이 낮은 사이트를 업그레이드한 뒤 나머지를 진행합니다.
# Rollback is a one-line change if both FPM versions remain installed
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
# fastcgi_pass unix:/run/php/php8.2-fpm.sock;

공유 호스팅에서는 cPanel의 MultiPHP Manager나 Select PHP Version의 버전 드롭다운, 또는 Plesk의 PHP 설정 페이지가 이에 해당합니다. WordPress에 특화된 절차는 WordPress에서 PHP 업데이트하는 방법을 참고하십시오.

7단계: 업그레이드 및 확인

전환한 후에는 다음을 수행합니다.

  • CLI뿐 아니라 웹 서버가 서비스하는 버전을 확인합니다. 호스팅 패널, WordPress 사이트 건강, 또는 확인 후 바로 삭제하는 임시 phpinfo() 페이지를 이용하십시오. PHP 버전 확인 방법을 참고하십시오.
  • 처음 몇 시간 동안 PHP와 웹 서버 오류 로그를 면밀히 살펴봅니다.
  • 예약 작업은 다음 실행 후에 확인합니다.
  • X-Powered-By 헤더가 새 버전을 노출하지 않는지 확인하고, 노출한다면 expose_php = Off로 설정합니다.

8단계: 이전 버전 제거하기

운영 환경이 합의된 기간 동안 안정적으로 동작했다면, 이전 PHP 패키지나 이미지를 제거하십시오. 남아 있는 런타임은 잊히기 쉽고, 이후 패치를 놓치며, cron 작업이나 스크립트가 실수로 사용하게 되기도 합니다.

다음 업그레이드를 더 쉽게 만들기

  • 사용 중단 알림을 업그레이드 시점까지 미루지 말고 지속적으로 수정하십시오.
  • 현재 PHP 버전과 다음 PHP 버전 모두에 대해 CI를 실행하십시오.
  • 의존성을 적당히 최신 상태로 유지해, PHP 업그레이드가 프레임워크 업그레이드로까지 번지지 않도록 하십시오.
  • 브랜치 종료일을 추적하고, 보안 지원이 끝나기 최소 6개월 전에 계획을 시작하십시오.

PHP 버전 검사기는 모든 업스트림 버전의 수명 주기 상태와 알려진 취약점을 보여 주므로, 각 업그레이드를 얼마나 빨리 진행해야 할지 결정하는 데 도움이 됩니다.

출처

  1. PHP: Supported Versions
  2. PHPCompatibility for PHP_CodeSniffer
  3. Rector
  4. PHP 8 ChangeLog