엔터프라이즈 코드베이스에서 엄격한 PHPStan 베이스라인의 필요성

Source: Dev.to

Problem

레거시 PHP 애플리케이션을 현대화하는 과정에서는 역설적인 상황에 직면합니다. 미래 버그를 방지하기 위해 PHPStan 같은 정적 분석 도구를 엄격히 적용해야 하지만, 이를 켜면 즉시 수천 개의 오류가 발생해 CI 파이프라인이 완전히 중단됩니다.

최근 엔터프라이즈 플랫폼(rlh‑core)에서 진행한 안정화 프로젝트에서는 비즈니스 로직은 훌륭했지만 반환 타입 누락, 느슨한 배열 정의, empty($message)와 같은 체크 대신 엄격한 null 체크가 부족한 경우가 많았습니다.
순진한 접근법이라면 한 달 동안 기능 개발을 중단하고 팀에게 기존 오류를 모두 수정하도록 강요해 PHPStan이 초록색을 반환하도록 만드는 것이지만, 이는 재정적으로 지속 가능하지 않습니다.
반대로 PHPStan을 비활성화하면 기술 부채가 검증 없이 쌓이게 됩니다.

Solution: PHPStan Baseline Pattern

1. PHPStan을 최대 엄격도(Level 8)로 설정합니다.

2. 전체 코드베이스에 대해 실행하고 결과를 베이스라인 파일에 파이프합니다:

   vendor/bin/phpstan analyse -c phpstan.neon --error-format=raw > phpstan-baseline.neon

   생성된 phpstan-baseline.neon은 기존 기술 부채의 암호화 서명 역할을 하며, CI 파이프라인이 해당 라인에 있는 특정 오류들을 무시하도록 합니다.

3. 베이스라인을 커밋합니다. 이제 CI 파이프라인은 초록색을 유지하면서도 새로운 코드에 대해서는 엄격한 Level 8 규칙이 적용됩니다.

4. 베이스라인 규칙을 강제합니다: 새로운 기능을 위해 파일이 수정될 경우, 해당 파일에 존재하는 베이스라인 오류는 반드시 해결해야 합니다.

5. 자동 정리: 엔지니어가 문제를 수정하면(예: empty()를 엄격한 null 체크로 교체) PHPStan은 오류가 사라졌음을 감지하고 베이스라인에서 해당 항목을 제거하도록 안내합니다(reportUnmatched: true).

Results

• 6개월 동안 베이스라인 오류가 약 5,000개에서 300개 이하로 감소했으며, 별도의 리팩터링 스프린트를 진행하지 않았습니다.
• 엄격한 규칙을 위반하는 새로운 코드는 빌드가 실패해 추가 부채가 발생하는 것을 방지합니다.
• 새로운 코드에 대해 엄격한 경계를 적용하면서 점진적으로 레거시 문제를 제거함으로써 애플리케이션이 매우 결정적이고 타입‑안전하게 되었습니다.

Takeaway

엔터프라이즈 기술 부채를 다룰 때 전략은 “집을 불태우는 것”이 아니라, 새로운 개발에 대해 엄격한 정적 분석을 적용해 불에 연료를 더하지 않는 것입니다. 이를 통해 기존 문제를 체계적으로 제거하면서도 새로운 부채는 발생하지 않게 할 수 있습니다.

Originally published at VictorStack AI — Drupal & WordPress Reference.